1podman-build(1) General Commands Manual podman-build(1)
2
6 podman-build - Build a container image using a Containerfile
7
10 podman build [options] [context]
11 podman image build [options] [context]
14
17 podman build Builds an image using instructions from one or more Con‐
18 tainerfiles or Dockerfiles and a specified build context directory. A
19 Containerfile uses the same syntax as a Dockerfile internally. For this
20 document, a file referred to as a Containerfile can be a file named ei‐
21 ther 'Containerfile' or 'Dockerfile'.
22 The build context directory can be specified as the http(s) URL of an
25 archive, git repository or Containerfile.
26 When invoked with -f and a path to a Containerfile, with no explicit
29 CONTEXT directory, Podman uses the Containerfile's parent directory as
30 its build context.
31 Containerfiles ending with a ".in" suffix are preprocessed via CPP(1).
34 This can be useful to decompose Containerfiles into several reusable
35 parts that can be used via CPP's #include directive. Containerfiles
36 ending in .in are restricted to no comment lines unless they are CPP
37 commands. Note, a Containerfile.in file can still be used by other
38 tools when manually preprocessing them via cpp -E.
39 When the URL is an archive, the contents of the URL is downloaded to a
42 temporary location and extracted before execution.
43 When the URL is a Containerfile, the Containerfile is downloaded to a
46 temporary location.
47 When a Git repository is set as the URL, the repository is cloned lo‐
50 cally and then set as the context.
51 NOTE: podman build uses code sourced from the Buildah project to build
54 container images. This Buildah code creates Buildah containers for the
55 RUN options in container storage. In certain situations, when the pod‐
56 man build crashes or users kill the podman build process, these exter‐
57 nal containers can be left in container storage. Use the podman ps
58 --all --storage command to see these containers. External containers
59 can be removed with the podman rm --storage command.
60 podman buildx build command is an alias of podman build. Not all
63 buildx build features are available in Podman. The buildx build option
64 is provided for scripting compatibility.
65
68 --add-host=host:ip
69 Add a custom host-to-IP mapping (host:ip)
70 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
73 tion can be set multiple times. Conflicts with the --no-hosts option.
74 --all-platforms
77 Instead of building for a set of platforms specified using the --plat‐
78 form option, inspect the build's base images, and build for all of the
79 platforms for which they are all available. Stages that use scratch as
80 a starting point can not be inspected, so at least one non-scratch
81 stage must be present for detection to work usefully.
82 --annotation=annotation
85 Add an image annotation (e.g. annotation=value) to the image metadata.
86 Can be used multiple times.
87 Note: this information is not present in Docker image formats, so it is
90 discarded when writing images in Docker formats.
91 --arch=arch
94 Set the architecture of the image to be built, and that of the base im‐
95 age to be pulled, if the build uses one, to the provided value instead
96 of using the architecture of the build host. Unless overridden, subse‐
97 quent lookups of the same image in the local storage matches this ar‐
98 chitecture, regardless of the host. (Examples: arm, arm64, 386, amd64,
99 ppc64le, s390x)
100 --authfile=path
103 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
104 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
105 dows/macOS. The file is created by podman login. If the authorization
106 state is not found there, $HOME/.docker/config.json is checked, which
107 is set using docker login.
108 Note: There is also the option to override the default path of the au‐
111 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
112 able. This can be done with export REGISTRY_AUTH_FILE=path.
113 --build-arg=arg=value
116 Specifies a build argument and its value, which is interpolated in in‐
117 structions read from the Containerfiles in the same way that environ‐
118 ment variables are, but which are not added to environment variable
119 list in the resulting image's configuration.
120 --build-arg-file=path
123 Specifies a file containing lines of build arguments of the form
124 arg=value. The suggested file name is argfile.conf.
125 Comment lines beginning with # are ignored, along with blank lines.
128 All others must be of the arg=value format passed to --build-arg.
129 If several arguments are provided via the --build-arg-file and --build-
132 arg options, the build arguments are merged across all of the provided
133 files and command line arguments.
134 Any file provided in a --build-arg-file option is read before the argu‐
137 ments supplied via the --build-arg option.
138 When a given argument name is specified several times, the last in‐
141 stance is the one that is passed to the resulting builds. This means
142 --build-arg values always override those in a --build-arg-file.
143 --build-context=name=value
146 Specify an additional build context using its short name and its loca‐
147 tion. Additional build contexts can be referenced in the same manner
148 as we access different stages in COPY instruction.
149 Valid values are:
152 • Local directory – e.g. --build-context
155 project2=../path/to/project2/src (This option is not available
156 with the remote Podman client. On Podman machine setup (i.e
157 macOS and Winows) path must exists on the machine VM)
158 • HTTP URL to a tarball – e.g. --build-context src=https://exam‐
160 ple.org/releases/src.tar
161 • Container image – specified with a container-image:// prefix,
163 e.g. --build-context alpine=container-image://alpine:3.15,
164 (also accepts docker://, docker-image://)
165 On the Containerfile side, reference the build context on all commands
169 that accept the “from” parameter. Here’s how that might look:
170 FROM [name]
173 COPY --from=[name] ...
174 RUN --mount=from=[name] …
175 The value of [name] is matched with the following priority order:
179 • Named build context defined with --build-context [name]=..
182 • Stage defined with AS [name] inside Containerfile
184 • Image [name], either local or in a remote registry
186 --cache-from
190 Repository to utilize as a potential cache source. When specified,
191 Buildah tries to look for cache images in the specified repository and
192 attempts to pull cache images instead of actually executing the build
193 steps locally. Buildah only attempts to pull previously cached images
194 if they are considered as valid cache hits.
195 Use the --cache-to option to populate a remote repository with cache
198 content.
199 Example
202 # populate a cache and also consult it
205 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
206 Note: --cache-from option is ignored unless --layers is specified.
210 --cache-to
213 Set this flag to specify a remote repository that is used to store
214 cache images. Buildah attempts to push newly built cache image to the
215 remote repository.
216 Note: Use the --cache-from option in order to use cache content in a
219 remote repository.
220 Example
223 # populate a cache and also consult it
226 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
227 Note: --cache-to option is ignored unless --layers is specified.
231 --cache-ttl
234 Limit the use of cached images to only consider images with created
235 timestamps less than duration ago. For example if --cache-ttl=1h is
236 specified, Buildah considers intermediate cache images which are cre‐
237 ated under the duration of one hour, and intermediate cache images out‐
238 side this duration is ignored.
239 Note: Setting --cache-ttl=0 manually is equivalent to using --no-cache
242 in the implementation since this means that the user dones not want to
243 use cache at all.
244 --cap-add=CAP_xxx
247 When executing RUN instructions, run the command specified in the in‐
248 struction with the specified capability added to its capability set.
249 Certain capabilities are granted by default; this option can be used to
250 add more.
251 --cap-drop=CAP_xxx
254 When executing RUN instructions, run the command specified in the in‐
255 struction with the specified capability removed from its capability
256 set. The CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID,
257 CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP,
258 and CAP_SETUID capabilities are granted by default; this option can be
259 used to remove them.
260 If a capability is specified to both the --cap-add and --cap-drop op‐
263 tions, it is dropped, regardless of the order in which the options were
264 given.
265 --cert-dir=path
268 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
269 istry. (Default: /etc/containers/certs.d) For details, see containers-
270 certs.d(5). (This option is not available with the remote Podman
271 client, including Mac and Windows (excluding WSL2) machines)
272 --cgroup-parent=path
275 Path to cgroups under which the cgroup for the container is created. If
276 the path is not absolute, the path is considered to be relative to the
277 cgroups path of the init process. Cgroups are created if they do not
278 already exist.
279 --cgroupns=how
282 Sets the configuration for cgroup namespaces when handling RUN instruc‐
283 tions. The configured value can be "" (the empty string) or "private"
284 to indicate that a new cgroup namespace is created, or it can be "host"
285 to indicate that the cgroup namespace in which buildah itself is being
286 run is reused.
287 --compress
290 This option is added to be aligned with other containers CLIs. Podman
291 doesn't communicate with a daemon or a remote server. Thus, compress‐
292 ing the data before sending it is irrelevant to Podman. (This option is
293 not available with the remote Podman client, including Mac and Windows
294 (excluding WSL2) machines)
295 --cpp-flag=flags
298 Set additional flags to pass to the C Preprocessor cpp(1). Container‐
299 files ending with a ".in" suffix is preprocessed via cpp(1). This op‐
300 tion can be used to pass additional flags to cpp.Note: You can also set
301 default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment variable
302 (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").
303 --cpu-period=limit
306 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
307 duration in microseconds. Once the container's CPU quota is used up, it
308 will not be scheduled to run until the current period ends. Defaults to
309 100000 microseconds.
310 On some systems, changing the resource limits may not be allowed for
313 non-root users. For more details, see https://github.com/contain‐
314 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
315 source-limits-fails-with-a-permissions-error
316 This option is not supported on cgroups V1 rootless systems.
319 --cpu-quota=limit
322 Limit the CPU Completely Fair Scheduler (CFS) quota.
323 Limit the container's CPU usage. By default, containers run with the
326 full CPU resource. The limit is a number in microseconds. If a number
327 is provided, the container is allowed to use that much CPU time until
328 the CPU period ends (controllable via --cpu-period).
329 On some systems, changing the resource limits may not be allowed for
332 non-root users. For more details, see https://github.com/contain‐
333 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
334 source-limits-fails-with-a-permissions-error
335 This option is not supported on cgroups V1 rootless systems.
338 --cpu-shares, -c=shares
341 CPU shares (relative weight).
342 By default, all containers get the same proportion of CPU cycles. This
345 proportion can be modified by changing the container's CPU share
346 weighting relative to the combined weight of all the running contain‐
347 ers. Default weight is 1024.
348 The proportion only applies when CPU-intensive processes are running.
351 When tasks in one container are idle, other containers can use the
352 left-over CPU time. The actual amount of CPU time varies depending on
353 the number of containers running on the system.
354 For example, consider three containers, one has a cpu-share of 1024 and
357 two others have a cpu-share setting of 512. When processes in all three
358 containers attempt to use 100% of CPU, the first container receives 50%
359 of the total CPU time. If a fourth container is added with a cpu-share
360 of 1024, the first container only gets 33% of the CPU. The remaining
361 containers receive 16.5%, 16.5% and 33% of the CPU.
362 On a multi-core system, the shares of CPU time are distributed over all
365 CPU cores. Even if a container is limited to less than 100% of CPU
366 time, it can use 100% of each individual CPU core.
367 For example, consider a system with more than three cores. If the con‐
370 tainer C0 is started with --cpu-shares=512 running one process, and an‐
371 other container C1 with --cpu-shares=1024 running two processes, this
372 can result in the following division of CPU shares:
373 ┌────┬───────────┬─────┬──────────────┐
376 │PID │ container │ CPU │ CPU share │
377 ├────┼───────────┼─────┼──────────────┤
378 │100 │ C0 │ 0 │ 100% of CPU0 │
379 ├────┼───────────┼─────┼──────────────┤
380 │101 │ C1 │ 1 │ 100% of CPU1 │
381 ├────┼───────────┼─────┼──────────────┤
382 │102 │ C1 │ 2 │ 100% of CPU2 │
383 └────┴───────────┴─────┴──────────────┘
384 On some systems, changing the resource limits may not be allowed for
386 non-root users. For more details, see https://github.com/contain‐
387 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
388 source-limits-fails-with-a-permissions-error
389 This option is not supported on cgroups V1 rootless systems.
392 --cpuset-cpus=number
395 CPUs in which to allow execution. Can be specified as a comma-separated
396 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
397 (e.g. 0-3,7,11-15).
398 On some systems, changing the resource limits may not be allowed for
401 non-root users. For more details, see https://github.com/contain‐
402 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
403 source-limits-fails-with-a-permissions-error
404 This option is not supported on cgroups V1 rootless systems.
407 --cpuset-mems=nodes
410 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
411 tive on NUMA systems.
412 If there are four memory nodes on the system (0-3), use --cpuset-
415 mems=0,1 then processes in the container only uses memory from the
416 first two memory nodes.
417 On some systems, changing the resource limits may not be allowed for
420 non-root users. For more details, see https://github.com/contain‐
421 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
422 source-limits-fails-with-a-permissions-error
423 This option is not supported on cgroups V1 rootless systems.
426 --creds=[username[:password]]
429 The [username[:password]] to use to authenticate with the registry, if
430 required. If one or both values are not supplied, a command line
431 prompt appears and the value can be entered. The password is entered
432 without echo.
433 Note that the specified credentials are only used to authenticate
436 against target registries. They are not used for mirrors or when the
437 registry gets rewritten (see containers-registries.conf(5)); to authen‐
438 ticate against those consider using a containers-auth.json(5) file.
439 --cw=options
442 Produce an image suitable for use as a confidential workload running in
443 a trusted execution environment (TEE) using krun (i.e., crun built with
444 the libkrun feature enabled and invoked as krun). Instead of the con‐
445 ventional contents, the root filesystem of the image will contain an
446 encrypted disk image and configuration information for krun.
447 The value for options is a comma-separated list of key=value pairs,
450 supplying configuration information which is needed for producing the
451 additional data which will be included in the container image.
452 Recognized keys are:
455 attestation_url: The location of a key broker / attestation server. If
458 a value is specified, the new image's workload ID, along with the
459 passphrase used to encrypt the disk image, will be registered with the
460 server, and the server's location will be stored in the container im‐
461 age. At run-time, krun is expected to contact the server to retrieve
462 the passphrase using the workload ID, which is also stored in the con‐
463 tainer image. If no value is specified, a passphrase value must be
464 specified.
465 cpus: The number of virtual CPUs which the image expects to be run with
468 at run-time. If not specified, a default value will be supplied.
469 firmware_library: The location of the libkrunfw-sev shared library. If
472 not specified, buildah checks for its presence in a number of hard-
473 coded locations.
474 memory: The amount of memory which the image expects to be run with at
477 run-time, as a number of megabytes. If not specified, a default value
478 will be supplied.
479 passphrase: The passphrase to use to encrypt the disk image which will
482 be included in the container image. If no value is specified, but an
483 attestation_url value is specified, a randomly-generated passphrase
484 will be used. The authors recommend setting an attestation_url but not
485 a passphrase.
486 slop: Extra space to allocate for the disk image compared to the size
489 of the container image's contents, expressed either as a percentage
490 (..%) or a size value (bytes, or larger units if suffixes like KB or MB
491 are present), or a sum of two or more such specifications. If not
492 specified, buildah guesses that 25% more space than the contents will
493 be enough, but this option is provided in case its guess is wrong.
494 type: The type of trusted execution environment (TEE) which the image
497 should be marked for use with. Accepted values are "SEV" (AMD Secure
498 Encrypted Virtualization - Encrypted State) and "SNP" (AMD Secure En‐
499 crypted Virtualization - Secure Nested Paging). If not specified, de‐
500 faults to "SNP".
501 workload_id: A workload identifier which will be recorded in the con‐
504 tainer image, to be used at run-time for retrieving the passphrase
505 which was used to encrypt the disk image. If not specified, a semi-
506 random value will be derived from the base image's image ID.
507 This option is not supported on the remote client, including Mac and
510 Windows (excluding WSL2) machines.
511 --decryption-key=key[:passphrase]
514 The [key[:passphrase]] to be used for decryption of images. Key can
515 point to keys and/or certificates. Decryption is tried with all keys.
516 If the key is protected by a passphrase, it is required to be passed in
517 the argument and omitted otherwise.
518 --device=host-device[:container-device][:permissions]
521 Add a host device to the container. Optional permissions parameter can
522 be used to specify device permissions by combining r for read, w for
523 write, and m for mknod(2).
524 Example: --device=/dev/sdc:/dev/xvdc:rwm.
527 Note: if host-device is a symbolic link then it is resolved first. The
530 container only stores the major and minor numbers of the host device.
531 Podman may load kernel modules required for using the specified device.
534 The devices that Podman loads modules for when necessary are:
535 /dev/fuse.
536 In rootless mode, the new device is bind mounted in the container from
539 the host rather than Podman creating it within the container space. Be‐
540 cause the bind mount retains its SELinux label on SELinux systems, the
541 container can get permission denied when accessing the mounted device.
542 Modify SELinux settings to allow containers to use all device labels
543 via the following command:
544 $ sudo setsebool -P container_use_devices=true
547 Note: if the user only has access rights via a group, accessing the de‐
550 vice from inside a rootless container fails. The crun(1) runtime offers
551 a workaround for this by adding the option --annotation
552 run.oci.keep_original_groups=1.
553 --disable-compression, -D
556 Don't compress filesystem layers when building the image unless it is
557 required by the location where the image is being written. This is the
558 default setting, because image layers are compressed automatically when
559 they are pushed to registries, and images being written to local stor‐
560 age only need to be decompressed again to be stored. Compression can
561 be forced in all cases by specifying --disable-compression=false.
562 --disable-content-trust
565 This is a Docker-specific option to disable image verification to a
566 container registry and is not supported by Podman. This option is a
567 NOOP and provided solely for scripting compatibility.
568 --dns=ipaddr
571 Set custom DNS servers.
572 This option can be used to override the DNS configuration passed to the
575 container. Typically this is necessary when the host DNS configuration
576 is invalid for the container (e.g., 127.0.0.1). When this is the case
577 the --dns flag is necessary for every run.
578 The special value none can be specified to disable creation of /etc/re‐
581 solv.conf in the container by Podman. The /etc/resolv.conf file in the
582 image is used without changes.
583 This option cannot be combined with --network that is set to none.
586 Note: this option takes effect only during RUN instructions in the
589 build. It does not affect /etc/resolv.conf in the final image.
590 --dns-option=option
593 Set custom DNS options to be used during the build.
594 --dns-search=domain
597 Set custom DNS search domains to be used during the build.
598 --env=env[=value]
601 Add a value (e.g. env=value) to the built image. Can be used multiple
602 times. If neither = nor a value are specified, but env is set in the
603 current environment, the value from the current environment is added to
604 the image. To remove an environment variable from the built image, use
605 the --unsetenv option.
606 --file, -f=Containerfile
609 Specifies a Containerfile which contains instructions for building the
610 image, either a local file or an http or https URL. If more than one
611 Containerfile is specified, FROM instructions are only be accepted from
612 the last specified file.
613 If a build context is not specified, and at least one Containerfile is
616 a local file, the directory in which it resides is used as the build
617 context.
618 Specifying the option -f - causes the Containerfile contents to be read
621 from stdin.
622 --force-rm
625 Always remove intermediate containers after a build, even if the build
626 fails (default true).
627 --format
630 Control the format for the built image's manifest and configuration
631 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
632 fault) and docker (version 2, using schema format 2 for the manifest).
633 Note: You can also override the default format by setting the BUIL‐
636 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
637 --from
640 Overrides the first FROM instruction within the Containerfile. If
641 there are multiple FROM instructions in a Containerfile, only the first
642 is changed.
643 With the remote podman client, not all container transports work as ex‐
646 pected. For example, oci-archive:/x.tar references /x.tar on the remote
647 machine instead of on the client. When using podman remote clients it
648 is best to restrict use to containers-storage, and docker:// trans‐
649 ports.
650 --group-add=group | keep-groups
653 Assign additional groups to the primary user running within the con‐
654 tainer process.
655 • keep-groups is a special value that tells Buildah to keep the
658 supplementary group access.
659 Allows container to use the user's supplementary group access. If file
663 systems or devices are only accessible by the rootless user's group,
664 this flag tells the OCI runtime to pass the group access into the con‐
665 tainer. Currently only available with the crun OCI runtime. Note: keep-
666 groups is exclusive, other groups cannot be specified with this flag.
667 --help, -h
670 Print usage statement
671 --hooks-dir=path
674 Each *.json file in the path configures a hook for buildah build con‐
675 tainers. For more details on the syntax of the JSON files and the se‐
676 mantics of hook injection. Buildah currently support both the 1.0.0 and
677 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
678 This option may be set multiple times; paths from later options have
681 higher precedence.
682 For the annotation conditions, buildah uses any annotations set in the
685 generated OCI configuration.
686 For the bind-mount conditions, only mounts explicitly requested by the
689 caller via --volume are considered. Bind mounts that buildah inserts by
690 default (e.g. /dev/shm) are not considered.
691 If --hooks-dir is unset for root callers, Buildah currently defaults to
694 /usr/share/containers/oci/hooks.d and /etc/containers/oci/hooks.d in
695 order of increasing precedence. Using these defaults is deprecated. Mi‐
696 grate to explicitly setting --hooks-dir.
697 --http-proxy
700 By default proxy environment variables are passed into the container if
701 set for the Podman process. This can be disabled by setting the value
702 to false. The environment variables passed in include http_proxy,
703 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
704 those. This option is only needed when the host system must use a proxy
705 but the container does not use any proxy. Proxy environment variables
706 specified for the container in any other way overrides the values that
707 have been passed through from the host. (Other ways to specify the
708 proxy for the container include passing the values with the --env flag,
709 or hard coding the proxy environment at container build time.) When
710 used with the remote client it uses the proxy environment variables
711 that are set on the server process.
712 Defaults to true.
715 --identity-label
718 Adds default identity label io.buildah.version if set. (default true).
719 --ignorefile
722 Path to an alternative .containerignore file.
723 --iidfile=ImageIDfile
726 Write the built image's ID to the file. When --platform is specified
727 more than once, attempting to use this option triggers an error.
728 --ipc=how
731 Sets the configuration for IPC namespaces when handling RUN instruc‐
732 tions. The configured value can be "" (the empty string) or "con‐
733 tainer" to indicate that a new IPC namespace is created, or it can be
734 "host" to indicate that the IPC namespace in which podman itself is be‐
735 ing run is reused, or it can be the path to an IPC namespace which is
736 already in use by another process.
737 --isolation=type
740 Controls what type of isolation is used for running processes as part
741 of RUN instructions. Recognized types include oci (OCI-compatible run‐
742 time, the default), rootless (OCI-compatible runtime invoked using a
743 modified configuration and its --rootless option enabled, with --no-
744 new-keyring --no-pivot added to its create invocation, with network and
745 UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the
746 default for unprivileged users), and chroot (an internal wrapper that
747 leans more toward chroot(1) than container technology).
748 Note: You can also override the default isolation type by setting the
751 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
752 --jobs=number
755 Run up to N concurrent stages in parallel. If the number of jobs is
756 greater than 1, stdin is read from /dev/null. If 0 is specified, then
757 there is no limit in the number of jobs that run in parallel.
758 --label=label
761 Add an image label (e.g. label=value) to the image metadata. Can be
762 used multiple times.
763 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
766 in a Containerfile that specifies the list of Linux capabilities re‐
767 quired for the container to run properly. This label specified in a
768 container image tells Podman to run the container with just these capa‐
769 bilities. Podman launches the container with just the specified capa‐
770 bilities, as long as this list of capabilities is a subset of the de‐
771 fault list.
772 If the specified capabilities are not in the default set, Podman prints
775 an error message and runs the container with the default capabilities.
776 --layer-label=label[=value]
779 Add an intermediate image label (e.g. label=value) to the intermediate
780 image metadata. It can be used multiple times.
781 If label is named, but neither = nor a value is provided, then the la‐
784 bel is set to an empty value.
785 --layers
788 Cache intermediate images during the build process (Default is true).
789 Note: You can also override the default value of layers by setting the
792 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
793 --logfile=filename
796 Log output which is sent to standard output and standard error to the
797 specified file instead of to standard output and standard error. This
798 option is not supported on the remote client, including Mac and Windows
799 (excluding WSL2) machines.
800 --logsplit=bool-value
803 If --logfile and --platform are specified, the --logsplit option allows
804 end-users to split the log file for each platform into different files
805 in the following format: ${logfile}_${platform-os}_${platform-arch}.
806 This option is not supported on the remote client, including Mac and
807 Windows (excluding WSL2) machines.
808 --manifest=manifest
811 Name of the manifest list to which the image is added. Creates the man‐
812 ifest list if it does not exist. This option is useful for building
813 multi architecture images.
814 --memory, -m=number[unit]
817 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
818 g (gibibytes).
819 Allows the memory available to a container to be constrained. If the
822 host supports swap memory, then the -m memory setting can be larger
823 than physical RAM. If a limit of 0 is specified (not using -m), the
824 container's memory is not limited. The actual limit may be rounded up
825 to a multiple of the operating system's page size (the value is very
826 large, that's millions of trillions).
827 This option is not supported on cgroups V1 rootless systems.
830 --memory-swap=number[unit]
833 A limit value equal to memory plus swap. A unit can be b (bytes), k
834 (kibibytes), m (mebibytes), or g (gibibytes).
835 Must be used with the -m (--memory) flag. The argument value must be
838 larger than that of
839 -m (--memory) By default, it is set to double the value of --memory.
840 Set number to -1 to enable unlimited swap.
843 This option is not supported on cgroups V1 rootless systems.
846 --network=mode, --net
849 Sets the configuration for network namespaces when handling RUN in‐
850 structions.
851 Valid mode values are:
854 • none: no networking.
857 • host: use the Podman host network stack. Note: the host mode
859 gives the container full access to local system services such
860 as D-bus and is therefore considered insecure.
861 • ns:path: path to a network namespace to join.
863 • private: create a new namespace for the container (default)
865 • <network name|ID>: Join the network with the given name or ID,
867 e.g. use --network mynet to join the network with the name
868 mynet. Only supported for rootful users.
869 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
871 network stack. This is the default for rootless containers. It
872 is possible to specify these additional options, they can also
873 be set with network_cmd_options in containers.conf:
874 • allow_host_loopback=true|false: Allow slirp4netns to reach
876 the host loopback IP (default is 10.0.2.2 or the second IP
877 from slirp4netns cidr subnet when changed, see the cidr op‐
878 tion below). The default is false.
879 • mtu=MTU: Specify the MTU to use for this network. (Default
881 is 65520).
882 • cidr=CIDR: Specify ip range to use for this network. (De‐
884 fault is 10.0.2.0/24).
885 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
887 quired for outbound_addr6).
888 • outbound_addr=INTERFACE: Specify the outbound interface
890 slirp binds to (ipv4 traffic only).
891 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
893 binds to.
894 • outbound_addr6=INTERFACE: Specify the outbound interface
896 slirp binds to (ipv6 traffic only).
897 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
899 binds to.
900 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
904 working stack.
905 This is only supported in rootless mode.
906 By default, IPv4 and IPv6 addresses and routes, as well as the
907 pod interface name, are copied from the host. If port forward‐
908 ing isn't configured, ports are forwarded dynamically as ser‐
909 vices are bound on either side (init namespace or container
910 namespace). Port forwarding preserves the original source IP
911 address. Options described in pasta(1) can be specified as
912 comma-separated arguments.
913 In terms of pasta(1) options, --config-net is given by de‐
914 fault, in order to configure networking when the container is
915 started, and --no-map-gw is also assumed by default, to avoid
916 direct access from container to host using the gateway ad‐
917 dress. The latter can be overridden by passing --map-gw in the
918 pasta-specific options (despite not being an actual pasta(1)
919 option).
920 Also, -t none and -u none are passed to disable automatic port
921 forwarding based on bound ports. Similarly, -T none and -U
922 none are given to disable the same functionality from con‐
923 tainer to host.
924 Some examples:
925 • pasta:--map-gw: Allow the container to directly reach the
927 host using the gateway address.
928 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
930 terface in the container.
931 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
933 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
934 alent to default slirp4netns(1) options: disable IPv6, as‐
935 sign 10.0.2.0/24 to the tap0 interface in the container,
936 with gateway 10.0.2.3, enable DNS forwarder reachable at
937 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
938 DHCP support.
939 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
941 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
942 to default slirp4netns(1) options with Podman overrides:
943 same as above, but leave the MTU to 65520 bytes
944 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
946 forwarding based on observed bound ports from both host and
947 container sides
948 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
950 tainer to host, using the loopback interface instead of the
951 tap interface for improved performance
952 --no-cache
958 Do not use existing cached images for the container build. Build from
959 the start with a new set of cached layers.
960 --no-hosts
963 Do not create /etc/hosts for the container. By default, Podman manages
964 /etc/hosts, adding the container's own IP address and any hosts from
965 --add-host. --no-hosts disables this, and the image's /etc/hosts is
966 preserved unmodified.
967 This option conflicts with --add-host.
970 --omit-history
973 Omit build history information in the built image. (default false).
974 This option is useful for the cases where end users explicitly want to
977 set --omit-history to omit the optional History from built images or
978 when working with images built using build tools that do not include
979 History information in their images.
980 --os=string
983 Set the OS of the image to be built, and that of the base image to be
984 pulled, if the build uses one, instead of using the current operating
985 system of the build host. Unless overridden, subsequent lookups of the
986 same image in the local storage matches this OS, regardless of the
987 host.
988 --os-feature=feature
991 Set the name of a required operating system feature for the image which
992 is built. By default, if the image is not based on scratch, the base
993 image's required OS feature list is kept, if the base image specified
994 any. This option is typically only meaningful when the image's OS is
995 Windows.
996 If feature has a trailing -, then the feature is removed from the set
999 of required features which is listed in the image.
1000 --os-version=version
1003 Set the exact required operating system version for the image which is
1004 built. By default, if the image is not based on scratch, the base im‐
1005 age's required OS version is kept, if the base image specified one.
1006 This option is typically only meaningful when the image's OS is Win‐
1007 dows, and is typically set in Windows base images, so using this option
1008 is usually unnecessary.
1009 --output, -o=output-opts
1012 Output destination (format: type=local,dest=path)
1013 The --output (or -o) option extends the default behavior of building a
1016 container image by allowing users to export the contents of the image
1017 as files on the local filesystem, which can be useful for generating
1018 local binaries, code generation, etc. (This option is not available
1019 with the remote Podman client, including Mac and Windows (excluding
1020 WSL2) machines)
1021 The value for --output is a comma-separated sequence of key=value
1024 pairs, defining the output type and options.
1025 Supported keys are: - dest: Destination path for exported output. Valid
1028 value is absolute or relative path, - means the standard output. -
1029 type: Defines the type of output to be used. Valid values is documented
1030 below.
1031 Valid type values are: - local: write the resulting build files to a
1034 directory on the client-side. - tar: write the resulting files as a
1035 single tarball (.tar).
1036 If no type is specified, the value defaults to local. Alternatively,
1039 instead of a comma-separated sequence, the value of --output can be
1040 just a destination (in the dest format) (e.g. --output some-path,
1041 --output -) where --output some-path is treated as if type=local and
1042 --output - is treated as if type=tar.
1043 --pid=pid
1046 Sets the configuration for PID namespaces when handling RUN instruc‐
1047 tions. The configured value can be "" (the empty string) or "con‐
1048 tainer" to indicate that a new PID namespace is created, or it can be
1049 "host" to indicate that the PID namespace in which podman itself is be‐
1050 ing run is reused, or it can be the path to a PID namespace which is
1051 already in use by another process.
1052 --platform=os/arch[/variant][,...]
1055 Set the os/arch of the built image (and its base image, when using one)
1056 to the provided value instead of using the current operating system and
1057 architecture of the host (for example linux/arm). Unless overridden,
1058 subsequent lookups of the same image in the local storage matches this
1059 platform, regardless of the host.
1060 If --platform is set, then the values of the --arch, --os, and --vari‐
1063 ant options is overridden.
1064 The --platform option can be specified more than once, or given a
1067 comma-separated list of values as its argument. When more than one
1068 platform is specified, the --manifest option is used instead of the
1069 --tag option.
1070 Os/arch pairs are those used by the Go Programming Language. In sev‐
1073 eral cases the arch value for a platform differs from one produced by
1074 other tools such as the arch command. Valid OS and architecture name
1075 combinations are listed as values for $GOOS and $GOARCH at
1076 https://golang.org/doc/install/source#environment, and can also be
1077 found by running go tool dist list.
1078 While podman build is happy to use base images and build images for any
1081 platform that exists, RUN instructions are able to succeed without the
1082 help of emulation provided by packages like qemu-user-static.
1083 --pull=policy
1086 Pull image policy. The default is always.
1087 • always, true: Always pull the image and throw an error if the
1090 pull fails.
1091 • missing: Only pull the image when it does not exist in the lo‐
1093 cal containers storage. Throw an error if no image is found
1094 and the pull fails.
1095 • never, false: Never pull the image but use the one from the
1097 local containers storage. Throw an error when no image is
1098 found.
1099 • newer: Pull if the image on the registry is newer than the one
1101 in the local containers storage. An image is considered to be
1102 newer when the digests are different. Comparing the time
1103 stamps is prone to errors. Pull errors are suppressed if a
1104 local image was found.
1105 --quiet, -q
1109 Suppress output messages which indicate which instruction is being pro‐
1110 cessed, and of progress when pulling images from a registry, and when
1111 writing the output image.
1112 --retry=attempts
1115 Number of times to retry in case of failure when performing pull of im‐
1116 ages from registry. Default is 3.
1117 --retry-delay=duration
1120 Duration of delay between retry attempts in case of failure when per‐
1121 forming pull of images from registry. Default is 2s.
1122 --rm
1125 Remove intermediate containers after a successful build (default true).
1126 --runtime=path
1129 The path to an alternate OCI-compatible runtime, which is used to run
1130 commands specified by the RUN instruction.
1131 Note: You can also override the default runtime by setting the BUIL‐
1134 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/lo‐
1135 cal/bin/runc
1136 --runtime-flag=flag
1139 Adds global flags for the container rutime. To list the supported
1140 flags, please consult the manpages of the selected container runtime.
1141 Note: Do not pass the leading -- to the flag. To pass the runc flag
1144 --log-format json to buildah build, the option given is --runtime-flag
1145 log-format=json.
1146 --secret=id=id,src=path
1149 Pass secret information used in the Containerfile for building images
1150 in a safe way that are not stored in the final image, or be seen in
1151 other stages. The secret is mounted in the container at the default
1152 location of /run/secrets/id.
1153 To later use the secret, use the --mount option in a RUN instruction
1156 within a Containerfile:
1157 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
1160 --security-opt=option
1163 Security Options
1164 • apparmor=unconfined : Turn off apparmor confinement for the
1167 container
1168 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1170 file for the container
1171 • label=user:USER : Set the label user for the container
1173 processes
1174 • label=role:ROLE : Set the label role for the container
1176 processes
1177 • label=type:TYPE : Set the label process type for the con‐
1179 tainer processes
1180 • label=level:LEVEL : Set the label level for the container
1182 processes
1183 • label=filetype:TYPE : Set the label file type for the con‐
1185 tainer files
1186 • label=disable : Turn off label separation for the con‐
1188 tainer
1189 • no-new-privileges : Not supported
1191 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1193 tainer
1194 • seccomp=profile.json : White listed syscalls seccomp Json
1196 file to be used as a seccomp filter
1197 --shm-size=number[unit]
1201 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1202 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1203 bytes. If the size is omitted, the default is 64m. When size is 0,
1204 there is no limit on the amount of memory used for IPC by the con‐
1205 tainer. This option conflicts with --ipc=host.
1206 --sign-by=fingerprint
1209 Sign the image using a GPG key with the specified FINGERPRINT. (This
1210 option is not available with the remote Podman client, including Mac
1211 and Windows (excluding WSL2) machines,)
1212 --skip-unused-stages
1215 Skip stages in multi-stage builds which don't affect the target stage.
1216 (Default: true).
1217 --squash
1220 Squash all of the image's new layers into a single new layer; any pre‐
1221 existing layers are not squashed.
1222 --squash-all
1225 Squash all of the new image's layers (including those inherited from a
1226 base image) into a single new layer.
1227 --ssh=default | id[=socket>
1230 SSH agent socket or keys to expose to the build. The socket path can
1231 be left empty to use the value of default=$SSH_AUTH_SOCK
1232 To later use the ssh agent, use the --mount option in a RUN instruction
1235 within a Containerfile:
1236 RUN --mount=type=ssh,id=id mycmd
1239 --stdin
1242 Pass stdin into the RUN containers. Sometime commands being RUN within
1243 a Containerfile want to request information from the user. For example
1244 apt asking for a confirmation for install. Use --stdin to be able to
1245 interact from the terminal during the build.
1246 --tag, -t=imageName
1249 Specifies the name which is assigned to the resulting image if the
1250 build process completes successfully. If imageName does not include a
1251 registry name, the registry name localhost is prepended to the image
1252 name.
1253 --target=stageName
1256 Set the target build stage to build. When building a Containerfile
1257 with multiple build stages, --target can be used to specify an interme‐
1258 diate build stage by name as the final stage for the resulting image.
1259 Commands after the target stage is skipped.
1260 --timestamp=seconds
1263 Set the create timestamp to seconds since epoch to allow for determin‐
1264 istic builds (defaults to current time). By default, the created time‐
1265 stamp is changed and written into the image manifest with every commit,
1266 causing the image's sha256 hash to be different even if the sources are
1267 exactly the same otherwise. When --timestamp is set, the created time‐
1268 stamp is always set to the time specified and therefore not changed,
1269 allowing the image's sha256 hash to remain the same. All files commit‐
1270 ted to the layers of the image is created with the timestamp.
1271 If the only instruction in a Containerfile is FROM, this flag has no
1274 effect.
1275 --tls-verify
1278 Require HTTPS and verify certificates when contacting registries (de‐
1279 fault: true). If explicitly set to true, TLS verification is used. If
1280 set to false, TLS verification is not used. If not specified, TLS ver‐
1281 ification is used unless the target registry is listed as an insecure
1282 registry in containers-registries.conf(5)
1283 --ulimit=type=soft-limit[:hard-limit]
1286 Specifies resource limits to apply to processes launched when process‐
1287 ing RUN instructions. This option can be specified multiple times.
1288 Recognized resource types include:
1289 "core": maximum core dump size (ulimit -c)
1290 "cpu": maximum CPU time (ulimit -t)
1291 "data": maximum size of a process's data segment (ulimit -d)
1292 "fsize": maximum size of new files (ulimit -f)
1293 "locks": maximum number of file locks (ulimit -x)
1294 "memlock": maximum amount of locked memory (ulimit -l)
1295 "msgqueue": maximum amount of data in message queues (ulimit -q)
1296 "nice": niceness adjustment (nice -n, ulimit -e)
1297 "nofile": maximum number of open files (ulimit -n)
1298 "nproc": maximum number of processes (ulimit -u)
1299 "rss": maximum size of a process's (ulimit -m)
1300 "rtprio": maximum real-time scheduling priority (ulimit -r)
1301 "rttime": maximum amount of real-time execution between blocking
1302 syscalls
1303 "sigpending": maximum number of pending signals (ulimit -i)
1304 "stack": maximum stack size (ulimit -s)
1305 --unsetenv=env
1308 Unset environment variables from the final image.
1309 --userns=how
1312 Sets the configuration for user namespaces when handling RUN instruc‐
1313 tions. The configured value can be "" (the empty string) or "con‐
1314 tainer" to indicate that a new user namespace is created, it can be
1315 "host" to indicate that the user namespace in which podman itself is
1316 being run is reused, or it can be the path to a user namespace which is
1317 already in use by another process.
1318 --userns-gid-map=mapping
1321 Directly specifies a GID mapping to be used to set ownership, at the
1322 filesystem level, on the working container's contents. Commands run
1323 when handling RUN instructions defaults to being run in their own user
1324 namespaces, configured using the UID and GID maps.
1325 Entries in this map take the form of one or more triples of a starting
1328 in-container GID, a corresponding starting host-level GID, and the num‐
1329 ber of consecutive IDs which the map entry represents.
1330 This option overrides the remap-gids setting in the options section of
1333 /etc/containers/storage.conf.
1334 If this option is not specified, but a global --userns-gid-map setting
1337 is supplied, settings from the global option is used.
1338 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1341 gid-map are specified, but --userns-uid-map is specified, the GID map
1342 is set to use the same numeric values as the UID map.
1343 --userns-gid-map-group=group
1346 Specifies that a GID mapping to be used to set ownership, at the
1347 filesystem level, on the working container's contents, can be found in
1348 entries in the /etc/subgid file which correspond to the specified
1349 group. Commands run when handling RUN instructions defaults to being
1350 run in their own user namespaces, configured using the UID and GID
1351 maps. If --userns-uid-map-user is specified, but --userns-gid-map-
1352 group is not specified, podman assumes that the specified user name is
1353 also a suitable group name to use as the default setting for this op‐
1354 tion.
1355 NOTE: When this option is specified by a rootless user, the specified
1358 mappings are relative to the rootless user namespace in the container,
1359 rather than being relative to the host as it is when run rootful.
1360 --userns-uid-map=mapping
1363 Directly specifies a UID mapping to be used to set ownership, at the
1364 filesystem level, on the working container's contents. Commands run
1365 when handling RUN instructions default to being run in their own user
1366 namespaces, configured using the UID and GID maps.
1367 Entries in this map take the form of one or more triples of a starting
1370 in-container UID, a corresponding starting host-level UID, and the num‐
1371 ber of consecutive IDs which the map entry represents.
1372 This option overrides the remap-uids setting in the options section of
1375 /etc/containers/storage.conf.
1376 If this option is not specified, but a global --userns-uid-map setting
1379 is supplied, settings from the global option is used.
1380 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1383 uid-map are specified, but --userns-gid-map is specified, the UID map
1384 is set to use the same numeric values as the GID map.
1385 --userns-uid-map-user=user
1388 Specifies that a UID mapping to be used to set ownership, at the
1389 filesystem level, on the working container's contents, can be found in
1390 entries in the /etc/subuid file which correspond to the specified user.
1391 Commands run when handling RUN instructions defaults to being run in
1392 their own user namespaces, configured using the UID and GID maps. If
1393 --userns-gid-map-group is specified, but --userns-uid-map-user is not
1394 specified, podman assumes that the specified group name is also a suit‐
1395 able user name to use as the default setting for this option.
1396 NOTE: When this option is specified by a rootless user, the specified
1399 mappings are relative to the rootless user namespace in the container,
1400 rather than being relative to the host as it is when run rootful.
1401 --uts=how
1404 Sets the configuration for UTS namespaces when handling RUN instruc‐
1405 tions. The configured value can be "" (the empty string) or "con‐
1406 tainer" to indicate that a new UTS namespace to be created, or it can
1407 be "host" to indicate that the UTS namespace in which podman itself is
1408 being run is reused, or it can be the path to a UTS namespace which is
1409 already in use by another process.
1410 --variant=variant
1413 Set the architecture variant of the image to be built, and that of the
1414 base image to be pulled, if the build uses one, to the provided value
1415 instead of using the architecture variant of the build host.
1416 --volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]
1419 Create a bind mount. Specifying the -v /HOST-DIR:/CONTAINER-DIR option,
1420 Podman bind mounts /HOST-DIR from the host to /CONTAINER-DIR in the
1421 Podman container.
1422 The OPTIONS are a comma-separated list and can be: [1] ⟨#Footnote1⟩
1425 • [rw|ro]
1428 • [z|Z|O]
1430 • [U]
1432 • [[r]shared|[r]slave|[r]private]
1434 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1438 DIR must be an absolute path as well. Podman bind-mounts the HOST-DIR
1439 to the specified path. For example, when specifying the host path /foo,
1440 Podman copies the contents of /foo to the container filesystem on the
1441 host and bind mounts that into the container.
1442 You can specify multiple -v options to mount one or more mounts to a
1445 container.
1446 You can add the :ro or :rw suffix to a volume to mount it read-only or
1449 read-write mode, respectively. By default, the volumes are mounted
1450 read-write. See examples.
1451 Chowning Volume Mounts
1454 By default, Podman does not change the owner and group of source volume
1457 directories mounted. When running using user namespaces, the UID and
1458 GID inside the namespace may correspond to another UID and GID on the
1459 host.
1460 The :U suffix tells Podman to use the correct host UID and GID based on
1463 the UID and GID within the namespace, to change recursively the owner
1464 and group of the source volume.
1465 Warning use with caution since this modifies the host filesystem.
1468 Labeling Volume Mounts
1471 Labeling systems like SELinux require that proper labels are placed on
1474 volume content mounted into a container. Without a label, the security
1475 system might prevent the processes running inside the container from
1476 using the content. By default, Podman does not change the labels set by
1477 the OS.
1478 To change a label in the container context, add one of these two suf‐
1481 fixes :z or :Z to the volume mount. These suffixes tell Podman to rela‐
1482 bel file objects on the shared volumes. The z option tells Podman that
1483 two containers share the volume content. As a result, Podman labels the
1484 content with a shared content label. Shared volume labels allow all
1485 containers to read/write content. The Z option tells Podman to label
1486 the content with a private unshared label. Only the current container
1487 can use a private volume.
1488 Note: Do not relabel system files and directories. Relabeling system
1491 content might cause other confined services on the host machine to
1492 fail. For these types of containers, disabling SELinux separation is
1493 recommended. The option --security-opt label=disable disables SELinux
1494 separation for the container. For example, if a user wanted to volume
1495 mount their entire home directory into the build containers, they need
1496 to disable SELinux separation.
1497 $ podman build --security-opt label=disable -v $HOME:/home/user .
1500 Overlay Volume Mounts
1504 The :O flag tells Podman to mount the directory from the host as a tem‐
1507 porary storage using the Overlay file system. The RUN command contain‐
1508 ers are allowed to modify contents within the mountpoint and are stored
1509 in the container storage in a separate directory. In Overlay FS terms
1510 the source directory is the lower, and the container storage directory
1511 is the upper. Modifications to the mount point are destroyed when the
1512 RUN command finishes executing, similar to a tmpfs mount point.
1513 Any subsequent execution of RUN commands sees the original source di‐
1516 rectory content, any changes from previous RUN commands no longer ex‐
1517 ists.
1518 One use case of the overlay mount is sharing the package cache from the
1521 host into the container to allow speeding up builds.
1522 Note:
1525 - Overlay mounts are not currently supported in rootless mode.
1528 - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
1529 Content mounted into the container is labeled with the private label.
1533 On SELinux systems, labels in the source directory needs to be
1534 readable by the container label. If not, SELinux container separation
1535 must be disabled for the container to work.
1536 - Modification of the directory volume mounted into the container
1537 with an overlay mount can cause unexpected failures. Do not modify the
1538 directory until the container finishes running.
1539 By default bind mounted volumes are private. That means any mounts done
1542 inside containers are not be visible on the host and vice versa. This
1543 behavior can be changed by specifying a volume mount propagation prop‐
1544 erty.
1545 When the mount propagation policy is set to shared, any mounts com‐
1548 pleted inside the container on that volume is visible to both the host
1549 and container. When the mount propagation policy is set to slave, one
1550 way mount propagation is enabled and any mounts completed on the host
1551 for that volume is visible only inside of the container. To control the
1552 mount propagation property of volume use the :[r]shared, :[r]slave or
1553 :[r]private propagation flag. For mount propagation to work on the
1554 source mount point (mount point where source dir is mounted on) has to
1555 have the right propagation properties. For shared volumes, the source
1556 mount point has to be shared. And for slave volumes, the source mount
1557 has to be either shared or slave. [1] ⟨#Footnote1⟩
1558 Use df <source-dir> to determine the source mount and then use findmnt
1561 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1562 erties of source mount, if findmnt utility is not available, the source
1563 mount point can be determined by looking at the mount entry in
1564 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1565 tion properties are specified. shared:X means the mount is shared,
1566 master:X means the mount is slave and if nothing is there that means
1567 the mount is private. [1] ⟨#Footnote1⟩
1568 To change propagation properties of a mount point use the mount com‐
1571 mand. For example, to bind mount the source directory /foo do mount
1572 --bind /foo /foo and mount --make-private --make-shared /foo. This con‐
1573 verts /foo into a shared mount point. The propagation properties of
1574 the source mount can be changed directly. For instance if / is the
1575 source mount for /foo, then use mount --make-shared / to convert / into
1576 a shared mount.
1577
1580 Build an image using local Containerfiles
1581 $ podman build .
1582 $ podman build -f Containerfile.simple .
1584 $ cat $HOME/Containerfile | podman build -f - .
1586 $ podman build -f Containerfile.simple -f Containerfile.notsosimple .
1588 $ podman build -f Containerfile.in $HOME
1590 $ podman build -t imageName .
1592 $ podman build --tls-verify=true -t imageName -f Containerfile.simple .
1594 $ podman build --tls-verify=false -t imageName .
1596 $ podman build --runtime-flag log-format=json .
1598 $ podman build --runtime-flag debug .
1600 $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .
1602 $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
1604 $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
1606 $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
1608 $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
1610 $ podman build --layers -t imageName .
1612 $ podman build --no-cache -t imageName .
1614 $ podman build --layers --force-rm -t imageName .
1616 $ podman build --no-cache --rm=false -t imageName .
1618 $ podman build --network mynet .
1620 Building a multi-architecture image using the --manifest option (requires
1624 emulation software)
1625 $ podman build --arch arm --manifest myimage /tmp/mysrc
1626 $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1628 $ podman build --arch s390x --manifest myimage /tmp/mysrc
1630 $ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
1632 $ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
1634 Building an image using a URL, Git repo, or archive
1638 The build context directory can be specified as a URL to a Container‐
1639 file, a Git repository, or URL to an archive. If the URL is a Contain‐
1640 erfile, it is downloaded to a temporary location and used as the con‐
1641 text. When a Git repository is set as the URL, the repository is cloned
1642 locally to a temporary location and then used as the context. Lastly,
1643 if the URL is an archive, it is downloaded to a temporary location and
1644 extracted before being used as the context.
1645 Building an image using a URL to a Containerfile
1648 Podman downloads the Containerfile to a temporary location and then use
1649 it as the build context.
1650 $ podman build https://10.10.10.1/podman/Containerfile
1653 Building an image using a Git repository
1657 Podman clones the specified GitHub repository to a temporary location
1658 and use it as the context. The Containerfile at the root of the reposi‐
1659 tory is used and it only works if the GitHub repository is a dedicated
1660 repository.
1661 $ podman build -t hello https://github.com/containers/PodmanHello.git
1664 $ podman run hello
1665 Note: Github does not support using git:// for performing clone opera‐
1669 tion due to recent changes in their security guidance
1670 (https://github.blog/2021-09-01-improving-git-protocol-security-
1671 github/). Use an https:// URL if the source repository is hosted on
1672 Github.
1673 Building an image using a URL to an archive
1676 Podman fetches the archive file, decompress it, and use its contents as
1677 the build context. The Containerfile at the root of the archive and the
1678 rest of the archive are used as the context of the build. Passing the
1679 -f PATH/Containerfile option as well tells the system to look for that
1680 file inside the contents of the archive.
1681 $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1684 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1688 'identity' (no compression).
1689
1692 .containerignore/.dockerignore
1693 If the file .containerignore or .dockerignore exists in the context di‐
1694 rectory, podman build reads its contents. Use the --ignorefile option
1695 to override the Podman uses the content to exclude files and directo‐
1696 ries from the context directory, when executing COPY and ADD directives
1697 in the Containerfile/Dockerfile
1698 The .containerignore and .dockerignore files use the same syntax; if
1701 both are in the context directory, podman build only uses .containerig‐
1702 nore.
1703 Users can specify a series of Unix shell globs in a .containerignore
1706 file to identify files/directories to exclude.
1707 Podman supports a special wildcard string ** which matches any number
1710 of directories (including zero). For example, */.go excludes all files
1711 that end with .go that are found in all directories.
1712 Example .containerignore file:
1715 # exclude this content for image
1718 */*.c
1719 **/output*
1720 src
1721 */*.c Excludes files and directories whose names ends with .c in any
1725 top level subdirectory. For example, the source file include/root‐
1726 less.c.
1727 **/output* Excludes files and directories starting with output from any
1730 directory.
1731 src Excludes files named src and the directory src as well as any con‐
1734 tent in it.
1735 Lines starting with ! (exclamation mark) can be used to make exceptions
1738 to exclusions. The following is an example .containerignore file that
1739 uses this mechanism:
1740 *.doc
1743 !Help.doc
1744 Exclude all doc files except Help.doc from the image.
1748 This functionality is compatible with the handling of .containerignore
1751 files described here:
1752 https://github.com/containers/common/blob/main/docs/containerig‐
1755 nore.5.md
1756 registries.conf (/etc/containers/registries.conf)
1759 registries.conf is the configuration file which specifies which con‐
1762 tainer registries is consulted when completing image names which do not
1763 include a registry or domain portion.
1764
1767 lastlog sparse file
1768 Using a useradd command within a Containerfile with a large UID/GID
1769 creates a large sparse file /var/log/lastlog. This can cause the build
1770 to hang forever. Go language does not support sparse files correctly,
1771 which can lead to some huge files being created in the container image.
1772 When using the useradd command within the build script, pass the --no-
1775 log-init or -l option to the useradd command. This option tells user‐
1776 add to stop creating the lastlog file.
1777
1780 podman(1), buildah(1), containers-certs.d(5), containers-reg‐
1781 istries.conf(5), crun(1), runc(8), useradd(8), podman-ps(1), podman-
1782 rm(1), Containerfile(5), containerignore(5)
1783
1786 Aug 2020, Additional options and .containerignore added by Dan Walsh
1787 <dwalsh@redhat.com>
1788 May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1791 December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1794
1797 1: The Podman project is committed to inclusivity, a core value of open
1798 source. The master and slave mount propagation terminology used here is
1799 problematic and divisive, and needs to be changed. However, these
1800 terms are currently used within the Linux kernel and must be used as-is
1801 at this time. When the kernel maintainers rectify this usage, Podman
1802 will follow suit immediately.
1803 podman-build(1)