LinuxCommandLibrary

podman-build

Build container images from a Dockerfile

TLDR

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

$ podman build [path/to/directory]
copy

Create an image with a specified tag
$ podman build --tag [image_name:version] [path/to/directory]
copy

Create an image from a non-standard file
$ podman build --file [Containerfile.different] .
copy

Create an image without using any previously cached images
$ podman build --no-cache [path/to/directory]
copy

Create an image suppressing all output
$ podman build --quiet [path/to/directory]
copy

SYNOPSIS

podman build [options] PATH | URL | -

PARAMETERS

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

DESCRIPTION

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.

CAVEATS

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.

BUILD CONTEXT

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

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.

ROOTLESS BUILDS

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.

HISTORY

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.

SEE ALSO

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

Copied to clipboard