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 | -

--add-host=HOST:IP
    Add a custom host-to-IP mapping (host:ip)

--annotation=KEY=VALUE
    Add an annotation to the image.

--arch=ARCH
    Set the architecture to build for. Defaults to host architecture

--build-arg=VAR=VALUE
    Set build-time variables.

--cache-from=IMAGE
    Images to consider as cache sources.

--cap-add=CAP
    Add Linux capabilities.

--cap-drop=CAP
    Drop Linux capabilities.

--cgroupns=mode
    Cgroup namespace to use for the build container.

--compress
    Compress the build context using gzip.

--contextdir=PATH
    Path to the build context directory.

--creds=username[:password]
    Registry credentials.

--device=DEVICE
    Add a device mapping to the container.

--disable-content-trust
    Skip image verification.

--dns=DNS
    Set custom DNS servers.

--dns-opt=OPTION
    Set DNS options.

--dns-search=DOMAIN
    Set custom DNS search domains.

--file=PATH
    Path to the Dockerfile/Containerfile.

--format=TYPE
    Set the image manifest format.

--gidmap=GIDMAP
    GID mapping for the rootless user namespace.

--group-add=GROUP
    Add additional groups to the container.

--http-proxy
    Enable HTTP proxy support.

--ignorefile=PATH
    Path to the .containerignore file.

--label=KEY=VALUE
    Set metadata for an image.

--layers
    Create intermediate layers for each instruction.

--manifest=PATH
    Create a manifest list instead of an image.

--memory=MEMORY
    Set memory limit.

--memory-swap=MEMORY
    Set swap limit equal to memory plus swap: '-1' to enable unlimited swap.

--network=MODE
    Set network mode. Use 'none' to create a container with no networking.

--no-cache
    Do not use cache when building the image.

--no-squash
    Do not squash image layers. WARNING: This option can cause problems.

--platform=PLATFORM
    Set the platform if server is multi-platform capable.

--pull=always|missing|never
    Pull images used in the Dockerfile before building.

--quiet
    Suppress the build output and print image ID on success

--rm
    Remove intermediate containers after a successful build.

--security-opt=OPTION
    Security options.

--sign-by=KEYID
    Sign the image with the indicated key. If trust policy is set to require signatures, this option will bypass signature verification during build.

--squash
    Squash newly built layers into a single new layer.

--tag=IMAGE
    Tag the image (e.g., `example.com/org/image:version`).

--target=STAGE
    Set the target build stage to build.

--timeout=SECONDS
    Set the build timeout.

--tls-verify
    Verify TLS when pulling images.

--uidmap=UIDMAP
    UID mapping for the rootless user namespace.

--ulimit=ULIMIT
    Ulimit options.

The `podman build` command builds container images using instructions from a Dockerfile, Containerfile, or other build context. It allows users to create reproducible and isolated environments based on these definitions. It is a versatile tool capable of building images locally or remotely. Podman Build supports various build strategies and allows image customization through command line options, environment variables and build stages. It avoids the need for a Docker daemon and promotes rootless operation, enhancing security and user convenience. It offers advanced features like buildah integration, multi-stage builds, and context directory management for optimized image creation.

Rootless builds may require setting up user namespaces. BuildKit features might have limited support compared to Docker. Context size can affect build performance. Some Dockerfile features might not be fully compatible with Podman.

The build context includes all files and directories needed to build the image. It's typically the directory containing the Dockerfile or Containerfile. Large build contexts can slow down builds, so it's essential to keep them minimal using a `.containerignore` file.

Multi-stage builds allow you to use multiple `FROM` statements in your Dockerfile/Containerfile. Each `FROM` statement starts a new build stage, and you can copy artifacts from one stage to another, resulting in smaller final images by excluding unnecessary dependencies.

Podman's ability to perform rootless builds is one of its key features, enhancing security by reducing the attack surface.
Rootless builds require the user to have a user namespace configured, which allows simulating root privileges within a container without actually requiring root access on the host system.

Podman build evolved as a daemon-less alternative to Docker build.
It aimed to provide a secure and rootless way to build container images.
It integrates with Buildah for low-level image manipulation.
It's now a standard tool for building OCI-compliant images.

podman(1), podman-run(1), docker(1), buildah(1)