podman build reads a Containerfile (or Dockerfile) and produces an OCI image, daemonless and rootless by default.
podman build is the drop-in for docker build. It reads the same Dockerfile syntax and tags the result the same way, but runs without a daemon, which changes how a few CI errors look.
What it does
podman build executes the instructions in a Containerfile or Dockerfile and commits the layers into a local OCI image. It uses Buildah under the hood, runs without a root daemon, and accepts the same -t and -f flags as docker build.
Path to the Containerfile/Dockerfile (default ./Containerfile or ./Dockerfile)
--build-arg <k=v>
Set a build-time variable for ARG
--platform <os/arch>
Build for a target platform (or list for multi-arch)
--no-cache
Do not reuse cached layers
--pull=always
Always re-pull the base image
In CI
When building inside a container (Podman-in-Podman), the default fuse-overlayfs storage often fails without extra privileges. Set --storage-driver=vfs (or storage.conf driver = "vfs") so builds work in an unprivileged container, at the cost of slower, larger storage.
Common errors in CI
"error creating build container: short-name resolution enforced ... no resolution" means the base image FROM line uses an unqualified name and registries.conf has short-name-mode = "enforcing"; use a fully qualified name like docker.io/library/node:20. "potentially insufficient UIDs or GIDs available in user namespace ... cannot set up namespace" means /etc/subuid and /etc/subgid lack a range for the user. "kernel does not support overlay" or "failed to mount overlay" inside a container is fixed with --storage-driver=vfs.
Frequently asked questions
podman build: Build Images in CI Rootless?
podman build is the drop-in for docker build. It reads the same Dockerfile syntax and tags the result the same way, but runs without a daemon, which changes how a few CI errors look.
What it does?
podman build executes the instructions in a Containerfile or Dockerfile and commits the layers into a local OCI image. It uses Buildah under the hood, runs without a root daemon, and accepts the same -t and -f flags as docker build.
In CI?
When building inside a container (Podman-in-Podman), the default fuse-overlayfs storage often fails without extra privileges. Set --storage-driver=vfs (or storage.conf driver = "vfs") so builds work in an unprivileged container, at the cost of slower, larger storage.
Common errors in CI?
"error creating build container: short-name resolution enforced ... no resolution" means the base image FROM line uses an unqualified name and registries.conf has short-name-mode = "enforcing"; use a fully qualified name like docker.io/library/node:20. "potentially insufficient UIDs or GIDs available in user namespace ...
