podman-build

Create an image using a Dockerfile or Containerfile in the specified directory

$ podman build [path/to/directory]

$ podman build --tag [image_name:version] [path/to/directory]

$ podman build --file [Containerfile.different] .

$ podman build --no-cache [path/to/directory]

$ podman build --quiet [path/to/directory]

podman build [OPTIONS] PATH | URL | -

-t, --tag name:tag
    Assigns a name and optional tag to the built image. Can be specified multiple times.

-f, --file path/to/Dockerfile
    Specifies the path to the Dockerfile (or Containerfile) to use instead of the default.

--build-arg name=value
    Sets build-time variables, accessible within the Dockerfile using ARG instructions.

--no-cache
    Prevents the build process from using cached layers. All layers will be rebuilt.

--pull
    Always attempt to pull a newer version of the base image if it exists in the registry.

--platform os/arch[/variant]
    Sets the target platform for the built image (e.g., linux/arm64).

--target stage-name
    Builds up to the specified stage in a multi-stage Dockerfile.

-v, --volume src:dest[:options]
    Mounts a volume into the container during the build process, useful for injecting dependencies.

--output path
    Writes the image to a tar archive at the specified path instead of storing it in local storage.

--squash
    Squashes the new layers into a single new layer. This creates a smaller image but loses layer history.

--secret id=mysecret,src=/path/to/secret
    Mounts a secret file into the build container, making it available for use during the build.

--ssh default|
    Allows accessing SSH agent sockets or SSH keys during the build process, similar to BuildKit.

--label key=value
    Adds metadata labels to the built image. Can be specified multiple times.

--network mode
    Sets the network mode for the build containers (e.g., host, none, bridge).

The podman-build command is used to construct OCI (Open Container Initiative) compatible container images from a build context. This context, typically a directory containing a Dockerfile (or Containerfile), is processed by Podman to execute the instructions defined in the build file. It supports multi-stage builds, caching of build layers, and various build-time configurations, enabling users to create optimized and reproducible images. podman-build is a core component of the Podman ecosystem, offering a robust and daemonless alternative to Docker's image building capabilities, emphasizing security and flexibility. It processes build arguments, pulls base images, executes commands, and layers file system changes to produce the final image.

While highly compatible with Dockerfiles, some advanced BuildKit features might behave differently or be unsupported in older Podman versions. Building in rootless mode might have implications for resource access and network configurations compared to rootful builds. The build context is crucial; ensure all necessary files are included and unnecessary ones are excluded via a .dockerignore or .containerignore file to optimize performance and security.

Podman natively recognizes both Dockerfile and Containerfile as build instruction files. The latter is a Podman-specific convention emphasizing its independence from Docker.

The build context is the set of files at the specified PATH or URL that are available to the build process. Only files and directories within this context can be referenced by instructions like COPY or ADD in the Dockerfile. It's recommended to use a .dockerignore or .containerignore file to exclude unnecessary files from the context, which can significantly speed up builds and reduce image size.

podman-build emerged as a key command within the Podman project, initiated by Red Hat, as a daemonless alternative to Docker. Its development has focused on providing a secure, flexible, and OCI-compliant way to build container images without requiring a persistent background daemon. This approach enhances system security and integration with traditional Linux tools. Over time, it has gained extensive compatibility with Dockerfile syntax and adopted features similar to Docker's BuildKit, while maintaining its distinct architecture.

podman images(1), podman run(1), podman push(1), buildah(1)