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]
172 COPY --from=[name] ...
173 RUN --mount=from=[name] …
174 The value of [name] is matched with the following priority order:
178 • Named build context defined with --build-context [name]=..
181 • Stage defined with AS [name] inside Containerfile
183 • Image [name], either local or in a remote registry
185 --cache-from
189 Repository to utilize as a potential cache source. When specified,
190 Buildah tries to look for cache images in the specified repository and
191 attempts to pull cache images instead of actually executing the build
192 steps locally. Buildah only attempts to pull previously cached images
193 if they are considered as valid cache hits.
194 Use the --cache-to option to populate a remote repository with cache
197 content.
198 Example
201 # populate a cache and also consult it
203 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
204 Note: --cache-from option is ignored unless --layers is specified.
208 --cache-to
211 Set this flag to specify a remote repository that is used to store
212 cache images. Buildah attempts to push newly built cache image to the
213 remote repository.
214 Note: Use the --cache-from option in order to use cache content in a
217 remote repository.
218 Example
221 # populate a cache and also consult it
223 buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
224 Note: --cache-to option is ignored unless --layers is specified.
228 --cache-ttl
231 Limit the use of cached images to only consider images with created
232 timestamps less than duration ago. For example if --cache-ttl=1h is
233 specified, Buildah considers intermediate cache images which are cre‐
234 ated under the duration of one hour, and intermediate cache images out‐
235 side this duration is ignored.
236 Note: Setting --cache-ttl=0 manually is equivalent to using --no-cache
239 in the implementation since this means that the user dones not want to
240 use cache at all.
241 --cap-add=CAP_xxx
244 When executing RUN instructions, run the command specified in the in‐
245 struction with the specified capability added to its capability set.
246 Certain capabilities are granted by default; this option can be used to
247 add more.
248 --cap-drop=CAP_xxx
251 When executing RUN instructions, run the command specified in the in‐
252 struction with the specified capability removed from its capability
253 set. The CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER, CAP_FSETID,
254 CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP,
255 and CAP_SETUID capabilities are granted by default; this option can be
256 used to remove them.
257 If a capability is specified to both the --cap-add and --cap-drop op‐
260 tions, it is dropped, regardless of the order in which the options were
261 given.
262 --cert-dir=path
265 Use certificates at path (*.crt, *.cert, *.key) to connect to the reg‐
266 istry. (Default: /etc/containers/certs.d) For details, see containers-
267 certs.d(5). (This option is not available with the remote Podman
268 client, including Mac and Windows (excluding WSL2) machines)
269 --cgroup-parent=path
272 Path to cgroups under which the cgroup for the container is created. If
273 the path is not absolute, the path is considered to be relative to the
274 cgroups path of the init process. Cgroups are created if they do not
275 already exist.
276 --cgroupns=how
279 Sets the configuration for cgroup namespaces when handling RUN instruc‐
280 tions. The configured value can be "" (the empty string) or "private"
281 to indicate that a new cgroup namespace is created, or it can be "host"
282 to indicate that the cgroup namespace in which buildah itself is being
283 run is reused.
284 --compress
287 This option is added to be aligned with other containers CLIs. Podman
288 doesn't communicate with a daemon or a remote server. Thus, compress‐
289 ing the data before sending it is irrelevant to Podman. (This option is
290 not available with the remote Podman client, including Mac and Windows
291 (excluding WSL2) machines)
292 --cpp-flag=flags
295 Set additional flags to pass to the C Preprocessor cpp(1). Container‐
296 files ending with a ".in" suffix is preprocessed via cpp(1). This op‐
297 tion can be used to pass additional flags to cpp.Note: You can also set
298 default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment variable
299 (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").
300 --cpu-period=limit
303 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
304 duration in microseconds. Once the container's CPU quota is used up, it
305 will not be scheduled to run until the current period ends. Defaults to
306 100000 microseconds.
307 On some systems, changing the resource limits may not be allowed for
310 non-root users. For more details, see https://github.com/contain‐
311 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
312 source-limits-fails-with-a-permissions-error
313 This option is not supported on cgroups V1 rootless systems.
316 --cpu-quota=limit
319 Limit the CPU Completely Fair Scheduler (CFS) quota.
320 Limit the container's CPU usage. By default, containers run with the
323 full CPU resource. The limit is a number in microseconds. If a number
324 is provided, the container is allowed to use that much CPU time until
325 the CPU period ends (controllable via --cpu-period).
326 On some systems, changing the resource limits may not be allowed for
329 non-root users. For more details, see https://github.com/contain‐
330 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
331 source-limits-fails-with-a-permissions-error
332 This option is not supported on cgroups V1 rootless systems.
335 --cpu-shares, -c=shares
338 CPU shares (relative weight).
339 By default, all containers get the same proportion of CPU cycles. This
342 proportion can be modified by changing the container's CPU share
343 weighting relative to the combined weight of all the running contain‐
344 ers. Default weight is 1024.
345 The proportion only applies when CPU-intensive processes are running.
348 When tasks in one container are idle, other containers can use the
349 left-over CPU time. The actual amount of CPU time varies depending on
350 the number of containers running on the system.
351 For example, consider three containers, one has a cpu-share of 1024 and
354 two others have a cpu-share setting of 512. When processes in all three
355 containers attempt to use 100% of CPU, the first container receives 50%
356 of the total CPU time. If a fourth container is added with a cpu-share
357 of 1024, the first container only gets 33% of the CPU. The remaining
358 containers receive 16.5%, 16.5% and 33% of the CPU.
359 On a multi-core system, the shares of CPU time are distributed over all
362 CPU cores. Even if a container is limited to less than 100% of CPU
363 time, it can use 100% of each individual CPU core.
364 For example, consider a system with more than three cores. If the con‐
367 tainer C0 is started with --cpu-shares=512 running one process, and an‐
368 other container C1 with --cpu-shares=1024 running two processes, this
369 can result in the following division of CPU shares:
370 ┌────┬───────────┬─────┬──────────────┐
373 │PID │ container │ CPU │ CPU share │
374 ├────┼───────────┼─────┼──────────────┤
375 │100 │ C0 │ 0 │ 100% of CPU0 │
376 ├────┼───────────┼─────┼──────────────┤
377 │101 │ C1 │ 1 │ 100% of CPU1 │
378 ├────┼───────────┼─────┼──────────────┤
379 │102 │ C1 │ 2 │ 100% of CPU2 │
380 └────┴───────────┴─────┴──────────────┘
381 On some systems, changing the resource limits may not be allowed for
383 non-root users. For more details, see https://github.com/contain‐
384 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
385 source-limits-fails-with-a-permissions-error
386 This option is not supported on cgroups V1 rootless systems.
389 --cpuset-cpus=number
392 CPUs in which to allow execution. Can be specified as a comma-separated
393 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
394 (e.g. 0-3,7,11-15).
395 On some systems, changing the resource limits may not be allowed for
398 non-root users. For more details, see https://github.com/contain‐
399 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
400 source-limits-fails-with-a-permissions-error
401 This option is not supported on cgroups V1 rootless systems.
404 --cpuset-mems=nodes
407 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
408 tive on NUMA systems.
409 If there are four memory nodes on the system (0-3), use --cpuset-
412 mems=0,1 then processes in the container only uses memory from the
413 first two memory nodes.
414 On some systems, changing the resource limits may not be allowed for
417 non-root users. For more details, see https://github.com/contain‐
418 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
419 source-limits-fails-with-a-permissions-error
420 This option is not supported on cgroups V1 rootless systems.
423 --creds=[username[:password]]
426 The [username[:password]] to use to authenticate with the registry, if
427 required. If one or both values are not supplied, a command line
428 prompt appears and the value can be entered. The password is entered
429 without echo.
430 Note that the specified credentials are only used to authenticate
433 against target registries. They are not used for mirrors or when the
434 registry gets rewritten (see containers-registries.conf(5)); to authen‐
435 ticate against those consider using a containers-auth.json(5) file.
436 --cw=options
439 Produce an image suitable for use as a confidential workload running in
440 a trusted execution environment (TEE) using krun (i.e., crun built with
441 the libkrun feature enabled and invoked as krun). Instead of the con‐
442 ventional contents, the root filesystem of the image will contain an
443 encrypted disk image and configuration information for krun.
444 The value for options is a comma-separated list of key=value pairs,
447 supplying configuration information which is needed for producing the
448 additional data which will be included in the container image.
449 Recognized keys are:
452 attestation_url: The location of a key broker / attestation server. If
455 a value is specified, the new image's workload ID, along with the
456 passphrase used to encrypt the disk image, will be registered with the
457 server, and the server's location will be stored in the container im‐
458 age. At run-time, krun is expected to contact the server to retrieve
459 the passphrase using the workload ID, which is also stored in the con‐
460 tainer image. If no value is specified, a passphrase value must be
461 specified.
462 cpus: The number of virtual CPUs which the image expects to be run with
465 at run-time. If not specified, a default value will be supplied.
466 firmware_library: The location of the libkrunfw-sev shared library. If
469 not specified, buildah checks for its presence in a number of hard-
470 coded locations.
471 memory: The amount of memory which the image expects to be run with at
474 run-time, as a number of megabytes. If not specified, a default value
475 will be supplied.
476 passphrase: The passphrase to use to encrypt the disk image which will
479 be included in the container image. If no value is specified, but an
480 attestation_url value is specified, a randomly-generated passphrase
481 will be used. The authors recommend setting an attestation_url but not
482 a passphrase.
483 slop: Extra space to allocate for the disk image compared to the size
486 of the container image's contents, expressed either as a percentage
487 (..%) or a size value (bytes, or larger units if suffixes like KB or MB
488 are present), or a sum of two or more such specifications. If not
489 specified, buildah guesses that 25% more space than the contents will
490 be enough, but this option is provided in case its guess is wrong.
491 type: The type of trusted execution environment (TEE) which the image
494 should be marked for use with. Accepted values are "SEV" (AMD Secure
495 Encrypted Virtualization - Encrypted State) and "SNP" (AMD Secure En‐
496 crypted Virtualization - Secure Nested Paging). If not specified, de‐
497 faults to "SNP".
498 workload_id: A workload identifier which will be recorded in the con‐
501 tainer image, to be used at run-time for retrieving the passphrase
502 which was used to encrypt the disk image. If not specified, a semi-
503 random value will be derived from the base image's image ID.
504 This option is not supported on the remote client, including Mac and
507 Windows (excluding WSL2) machines.
508 --decryption-key=key[:passphrase]
511 The [key[:passphrase]] to be used for decryption of images. Key can
512 point to keys and/or certificates. Decryption is tried with all keys.
513 If the key is protected by a passphrase, it is required to be passed in
514 the argument and omitted otherwise.
515 --device=host-device[:container-device][:permissions]
518 Add a host device to the container. Optional permissions parameter can
519 be used to specify device permissions by combining r for read, w for
520 write, and m for mknod(2).
521 Example: --device=/dev/sdc:/dev/xvdc:rwm.
524 Note: if host-device is a symbolic link then it is resolved first. The
527 container only stores the major and minor numbers of the host device.
528 Podman may load kernel modules required for using the specified device.
531 The devices that Podman loads modules for when necessary are:
532 /dev/fuse.
533 In rootless mode, the new device is bind mounted in the container from
536 the host rather than Podman creating it within the container space. Be‐
537 cause the bind mount retains its SELinux label on SELinux systems, the
538 container can get permission denied when accessing the mounted device.
539 Modify SELinux settings to allow containers to use all device labels
540 via the following command:
541 $ sudo setsebool -P container_use_devices=true
544 Note: if the user only has access rights via a group, accessing the de‐
547 vice from inside a rootless container fails. The crun(1) runtime offers
548 a workaround for this by adding the option --annotation
549 run.oci.keep_original_groups=1.
550 --disable-compression, -D
553 Don't compress filesystem layers when building the image unless it is
554 required by the location where the image is being written. This is the
555 default setting, because image layers are compressed automatically when
556 they are pushed to registries, and images being written to local stor‐
557 age only need to be decompressed again to be stored. Compression can
558 be forced in all cases by specifying --disable-compression=false.
559 --disable-content-trust
562 This is a Docker-specific option to disable image verification to a
563 container registry and is not supported by Podman. This option is a
564 NOOP and provided solely for scripting compatibility.
565 --dns=ipaddr
568 Set custom DNS servers.
569 This option can be used to override the DNS configuration passed to the
572 container. Typically this is necessary when the host DNS configuration
573 is invalid for the container (e.g., 127.0.0.1). When this is the case
574 the --dns flag is necessary for every run.
575 The special value none can be specified to disable creation of /etc/re‐
578 solv.conf in the container by Podman. The /etc/resolv.conf file in the
579 image is used without changes.
580 This option cannot be combined with --network that is set to none.
583 Note: this option takes effect only during RUN instructions in the
586 build. It does not affect /etc/resolv.conf in the final image.
587 --dns-option=option
590 Set custom DNS options to be used during the build.
591 --dns-search=domain
594 Set custom DNS search domains to be used during the build.
595 --env=env[=value]
598 Add a value (e.g. env=value) to the built image. Can be used multiple
599 times. If neither = nor a value are specified, but env is set in the
600 current environment, the value from the current environment is added to
601 the image. To remove an environment variable from the built image, use
602 the --unsetenv option.
603 --file, -f=Containerfile
606 Specifies a Containerfile which contains instructions for building the
607 image, either a local file or an http or https URL. If more than one
608 Containerfile is specified, FROM instructions are only be accepted from
609 the last specified file.
610 If a build context is not specified, and at least one Containerfile is
613 a local file, the directory in which it resides is used as the build
614 context.
615 Specifying the option -f - causes the Containerfile contents to be read
618 from stdin.
619 --force-rm
622 Always remove intermediate containers after a build, even if the build
623 fails (default true).
624 --format
627 Control the format for the built image's manifest and configuration
628 data. Recognized formats include oci (OCI image-spec v1.0, the de‐
629 fault) and docker (version 2, using schema format 2 for the manifest).
630 Note: You can also override the default format by setting the BUIL‐
633 DAH_FORMAT environment variable. export BUILDAH_FORMAT=docker
634 --from
637 Overrides the first FROM instruction within the Containerfile. If
638 there are multiple FROM instructions in a Containerfile, only the first
639 is changed.
640 With the remote podman client, not all container transports work as ex‐
643 pected. For example, oci-archive:/x.tar references /x.tar on the remote
644 machine instead of on the client. When using podman remote clients it
645 is best to restrict use to containers-storage, and docker:// trans‐
646 ports.
647 --group-add=group | keep-groups
650 Assign additional groups to the primary user running within the con‐
651 tainer process.
652 • keep-groups is a special value that tells Buildah to keep the
655 supplementary group access.
656 Allows container to use the user's supplementary group access. If file
660 systems or devices are only accessible by the rootless user's group,
661 this flag tells the OCI runtime to pass the group access into the con‐
662 tainer. Currently only available with the crun OCI runtime. Note: keep-
663 groups is exclusive, other groups cannot be specified with this flag.
664 --help, -h
667 Print usage statement
668 --hooks-dir=path
671 Each *.json file in the path configures a hook for buildah build con‐
672 tainers. For more details on the syntax of the JSON files and the se‐
673 mantics of hook injection. Buildah currently support both the 1.0.0 and
674 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
675 This option may be set multiple times; paths from later options have
678 higher precedence.
679 For the annotation conditions, buildah uses any annotations set in the
682 generated OCI configuration.
683 For the bind-mount conditions, only mounts explicitly requested by the
686 caller via --volume are considered. Bind mounts that buildah inserts by
687 default (e.g. /dev/shm) are not considered.
688 If --hooks-dir is unset for root callers, Buildah currently defaults to
691 /usr/share/containers/oci/hooks.d and /etc/containers/oci/hooks.d in
692 order of increasing precedence. Using these defaults is deprecated. Mi‐
693 grate to explicitly setting --hooks-dir.
694 --http-proxy
697 By default proxy environment variables are passed into the container if
698 set for the Podman process. This can be disabled by setting the value
699 to false. The environment variables passed in include http_proxy,
700 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
701 those. This option is only needed when the host system must use a proxy
702 but the container does not use any proxy. Proxy environment variables
703 specified for the container in any other way overrides the values that
704 have been passed through from the host. (Other ways to specify the
705 proxy for the container include passing the values with the --env flag,
706 or hard coding the proxy environment at container build time.) When
707 used with the remote client it uses the proxy environment variables
708 that are set on the server process.
709 Defaults to true.
712 --identity-label
715 Adds default identity label io.buildah.version if set. (default true).
716 --ignorefile
719 Path to an alternative .containerignore file.
720 --iidfile=ImageIDfile
723 Write the built image's ID to the file. When --platform is specified
724 more than once, attempting to use this option triggers an error.
725 --ipc=how
728 Sets the configuration for IPC namespaces when handling RUN instruc‐
729 tions. The configured value can be "" (the empty string) or "con‐
730 tainer" to indicate that a new IPC namespace is created, or it can be
731 "host" to indicate that the IPC namespace in which podman itself is be‐
732 ing run is reused, or it can be the path to an IPC namespace which is
733 already in use by another process.
734 --isolation=type
737 Controls what type of isolation is used for running processes as part
738 of RUN instructions. Recognized types include oci (OCI-compatible run‐
739 time, the default), rootless (OCI-compatible runtime invoked using a
740 modified configuration and its --rootless option enabled, with --no-
741 new-keyring --no-pivot added to its create invocation, with network and
742 UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the
743 default for unprivileged users), and chroot (an internal wrapper that
744 leans more toward chroot(1) than container technology).
745 Note: You can also override the default isolation type by setting the
748 BUILDAH_ISOLATION environment variable. export BUILDAH_ISOLATION=oci
749 --jobs=number
752 Run up to N concurrent stages in parallel. If the number of jobs is
753 greater than 1, stdin is read from /dev/null. If 0 is specified, then
754 there is no limit in the number of jobs that run in parallel.
755 --label=label
758 Add an image label (e.g. label=value) to the image metadata. Can be
759 used multiple times.
760 Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
763 in a Containerfile that specifies the list of Linux capabilities re‐
764 quired for the container to run properly. This label specified in a
765 container image tells Podman to run the container with just these capa‐
766 bilities. Podman launches the container with just the specified capa‐
767 bilities, as long as this list of capabilities is a subset of the de‐
768 fault list.
769 If the specified capabilities are not in the default set, Podman prints
772 an error message and runs the container with the default capabilities.
773 --layer-label=label[=value]
776 Add an intermediate image label (e.g. label=value) to the intermediate
777 image metadata. It can be used multiple times.
778 If label is named, but neither = nor a value is provided, then the la‐
781 bel is set to an empty value.
782 --layers
785 Cache intermediate images during the build process (Default is true).
786 Note: You can also override the default value of layers by setting the
789 BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
790 --logfile=filename
793 Log output which is sent to standard output and standard error to the
794 specified file instead of to standard output and standard error. This
795 option is not supported on the remote client, including Mac and Windows
796 (excluding WSL2) machines.
797 --logsplit=bool-value
800 If --logfile and --platform are specified, the --logsplit option allows
801 end-users to split the log file for each platform into different files
802 in the following format: ${logfile}_${platform-os}_${platform-arch}.
803 This option is not supported on the remote client, including Mac and
804 Windows (excluding WSL2) machines.
805 --manifest=manifest
808 Name of the manifest list to which the image is added. Creates the man‐
809 ifest list if it does not exist. This option is useful for building
810 multi architecture images.
811 --memory, -m=number[unit]
814 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
815 g (gibibytes).
816 Allows the memory available to a container to be constrained. If the
819 host supports swap memory, then the -m memory setting can be larger
820 than physical RAM. If a limit of 0 is specified (not using -m), the
821 container's memory is not limited. The actual limit may be rounded up
822 to a multiple of the operating system's page size (the value is very
823 large, that's millions of trillions).
824 This option is not supported on cgroups V1 rootless systems.
827 --memory-swap=number[unit]
830 A limit value equal to memory plus swap. A unit can be b (bytes), k
831 (kibibytes), m (mebibytes), or g (gibibytes).
832 Must be used with the -m (--memory) flag. The argument value must be
835 larger than that of
836 -m (--memory) By default, it is set to double the value of --memory.
837 Set number to -1 to enable unlimited swap.
840 This option is not supported on cgroups V1 rootless systems.
843 --network=mode, --net
846 Sets the configuration for network namespaces when handling RUN in‐
847 structions.
848 Valid mode values are:
851 • none: no networking.
854 • host: use the Podman host network stack. Note: the host mode
856 gives the container full access to local system services such
857 as D-bus and is therefore considered insecure.
858 • ns:path: path to a network namespace to join.
860 • private: create a new namespace for the container (default)
862 • <network name|ID>: Join the network with the given name or ID,
864 e.g. use --network mynet to join the network with the name
865 mynet. Only supported for rootful users.
866 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
868 network stack. This is the default for rootless containers. It
869 is possible to specify these additional options, they can also
870 be set with network_cmd_options in containers.conf:
871 • allow_host_loopback=true|false: Allow slirp4netns to reach
873 the host loopback IP (default is 10.0.2.2 or the second IP
874 from slirp4netns cidr subnet when changed, see the cidr op‐
875 tion below). The default is false.
876 • mtu=MTU: Specify the MTU to use for this network. (Default
878 is 65520).
879 • cidr=CIDR: Specify ip range to use for this network. (De‐
881 fault is 10.0.2.0/24).
882 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
884 quired for outbound_addr6).
885 • outbound_addr=INTERFACE: Specify the outbound interface
887 slirp binds to (ipv4 traffic only).
888 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
890 binds to.
891 • outbound_addr6=INTERFACE: Specify the outbound interface
893 slirp binds to (ipv6 traffic only).
894 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
896 binds to.
897 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
901 working stack.
902 This is only supported in rootless mode.
903 By default, IPv4 and IPv6 addresses and routes, as well as the
904 pod interface name, are copied from the host. If port forward‐
905 ing isn't configured, ports are forwarded dynamically as ser‐
906 vices are bound on either side (init namespace or container
907 namespace). Port forwarding preserves the original source IP
908 address. Options described in pasta(1) can be specified as
909 comma-separated arguments.
910 In terms of pasta(1) options, --config-net is given by de‐
911 fault, in order to configure networking when the container is
912 started, and --no-map-gw is also assumed by default, to avoid
913 direct access from container to host using the gateway ad‐
914 dress. The latter can be overridden by passing --map-gw in the
915 pasta-specific options (despite not being an actual pasta(1)
916 option).
917 Also, -t none and -u none are passed to disable automatic port
918 forwarding based on bound ports. Similarly, -T none and -U
919 none are given to disable the same functionality from con‐
920 tainer to host.
921 Some examples:
922 • pasta:--map-gw: Allow the container to directly reach the
924 host using the gateway address.
925 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
927 terface in the container.
928 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
930 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
931 alent to default slirp4netns(1) options: disable IPv6, as‐
932 sign 10.0.2.0/24 to the tap0 interface in the container,
933 with gateway 10.0.2.3, enable DNS forwarder reachable at
934 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
935 DHCP support.
936 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
938 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
939 to default slirp4netns(1) options with Podman overrides:
940 same as above, but leave the MTU to 65520 bytes
941 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
943 forwarding based on observed bound ports from both host and
944 container sides
945 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
947 tainer to host, using the loopback interface instead of the
948 tap interface for improved performance
949 --no-cache
955 Do not use existing cached images for the container build. Build from
956 the start with a new set of cached layers.
957 --no-hostname
960 Do not create the /etc/hostname file in the container for RUN instruc‐
961 tions.
962 By default, Buildah manages the /etc/hostname file, adding the con‐
965 tainer's own hostname. When the --no-hostname option is set, the im‐
966 age's /etc/hostname will be preserved unmodified if it exists.
967 --no-hosts
970 Do not create /etc/hosts for the container. By default, Podman manages
971 /etc/hosts, adding the container's own IP address and any hosts from
972 --add-host. --no-hosts disables this, and the image's /etc/hosts is
973 preserved unmodified.
974 This option conflicts with --add-host.
977 --omit-history
980 Omit build history information in the built image. (default false).
981 This option is useful for the cases where end users explicitly want to
984 set --omit-history to omit the optional History from built images or
985 when working with images built using build tools that do not include
986 History information in their images.
987 --os=string
990 Set the OS of the image to be built, and that of the base image to be
991 pulled, if the build uses one, instead of using the current operating
992 system of the build host. Unless overridden, subsequent lookups of the
993 same image in the local storage matches this OS, regardless of the
994 host.
995 --os-feature=feature
998 Set the name of a required operating system feature for the image which
999 is built. By default, if the image is not based on scratch, the base
1000 image's required OS feature list is kept, if the base image specified
1001 any. This option is typically only meaningful when the image's OS is
1002 Windows.
1003 If feature has a trailing -, then the feature is removed from the set
1006 of required features which is listed in the image.
1007 --os-version=version
1010 Set the exact required operating system version for the image which is
1011 built. By default, if the image is not based on scratch, the base im‐
1012 age's required OS version is kept, if the base image specified one.
1013 This option is typically only meaningful when the image's OS is Win‐
1014 dows, and is typically set in Windows base images, so using this option
1015 is usually unnecessary.
1016 --output, -o=output-opts
1019 Output destination (format: type=local,dest=path)
1020 The --output (or -o) option extends the default behavior of building a
1023 container image by allowing users to export the contents of the image
1024 as files on the local filesystem, which can be useful for generating
1025 local binaries, code generation, etc. (This option is not available
1026 with the remote Podman client, including Mac and Windows (excluding
1027 WSL2) machines)
1028 The value for --output is a comma-separated sequence of key=value
1031 pairs, defining the output type and options.
1032 Supported keys are: - dest: Destination path for exported output. Valid
1035 value is absolute or relative path, - means the standard output. -
1036 type: Defines the type of output to be used. Valid values is documented
1037 below.
1038 Valid type values are: - local: write the resulting build files to a
1041 directory on the client-side. - tar: write the resulting files as a
1042 single tarball (.tar).
1043 If no type is specified, the value defaults to local. Alternatively,
1046 instead of a comma-separated sequence, the value of --output can be
1047 just a destination (in the dest format) (e.g. --output some-path,
1048 --output -) where --output some-path is treated as if type=local and
1049 --output - is treated as if type=tar.
1050 --pid=pid
1053 Sets the configuration for PID namespaces when handling RUN instruc‐
1054 tions. The configured value can be "" (the empty string) or "con‐
1055 tainer" to indicate that a new PID namespace is created, or it can be
1056 "host" to indicate that the PID namespace in which podman itself is be‐
1057 ing run is reused, or it can be the path to a PID namespace which is
1058 already in use by another process.
1059 --platform=os/arch[/variant][,...]
1062 Set the os/arch of the built image (and its base image, when using one)
1063 to the provided value instead of using the current operating system and
1064 architecture of the host (for example linux/arm). Unless overridden,
1065 subsequent lookups of the same image in the local storage matches this
1066 platform, regardless of the host.
1067 If --platform is set, then the values of the --arch, --os, and --vari‐
1070 ant options is overridden.
1071 The --platform option can be specified more than once, or given a
1074 comma-separated list of values as its argument. When more than one
1075 platform is specified, the --manifest option is used instead of the
1076 --tag option.
1077 Os/arch pairs are those used by the Go Programming Language. In sev‐
1080 eral cases the arch value for a platform differs from one produced by
1081 other tools such as the arch command. Valid OS and architecture name
1082 combinations are listed as values for $GOOS and $GOARCH at
1083 https://golang.org/doc/install/source#environment, and can also be
1084 found by running go tool dist list.
1085 While podman build is happy to use base images and build images for any
1088 platform that exists, RUN instructions are able to succeed without the
1089 help of emulation provided by packages like qemu-user-static.
1090 --pull=policy
1093 Pull image policy. The default is missing.
1094 • always, true: Always pull the image and throw an error if the
1097 pull fails.
1098 • missing: Only pull the image when it does not exist in the lo‐
1100 cal containers storage. Throw an error if no image is found
1101 and the pull fails.
1102 • never, false: Never pull the image but use the one from the
1104 local containers storage. Throw an error when no image is
1105 found.
1106 • newer: Pull if the image on the registry is newer than the one
1108 in the local containers storage. An image is considered to be
1109 newer when the digests are different. Comparing the time
1110 stamps is prone to errors. Pull errors are suppressed if a
1111 local image was found.
1112 --quiet, -q
1116 Suppress output messages which indicate which instruction is being pro‐
1117 cessed, and of progress when pulling images from a registry, and when
1118 writing the output image.
1119 --retry=attempts
1122 Number of times to retry in case of failure when performing pull of im‐
1123 ages from registry. Default is 3.
1124 --retry-delay=duration
1127 Duration of delay between retry attempts in case of failure when per‐
1128 forming pull of images from registry. Default is 2s.
1129 --rm
1132 Remove intermediate containers after a successful build (default true).
1133 --runtime=path
1136 The path to an alternate OCI-compatible runtime, which is used to run
1137 commands specified by the RUN instruction.
1138 Note: You can also override the default runtime by setting the BUIL‐
1141 DAH_RUNTIME environment variable. export BUILDAH_RUNTIME=/usr/lo‐
1142 cal/bin/runc
1143 --runtime-flag=flag
1146 Adds global flags for the container rutime. To list the supported
1147 flags, please consult the manpages of the selected container runtime.
1148 Note: Do not pass the leading -- to the flag. To pass the runc flag
1151 --log-format json to buildah build, the option given is --runtime-flag
1152 log-format=json.
1153 --secret=id=id,src=path
1156 Pass secret information used in the Containerfile for building images
1157 in a safe way that are not stored in the final image, or be seen in
1158 other stages. The secret is mounted in the container at the default
1159 location of /run/secrets/id.
1160 To later use the secret, use the --mount option in a RUN instruction
1163 within a Containerfile:
1164 RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
1167 --security-opt=option
1170 Security Options
1171 • apparmor=unconfined : Turn off apparmor confinement for the
1174 container
1175 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1177 file for the container
1178 • label=user:USER : Set the label user for the container
1180 processes
1181 • label=role:ROLE : Set the label role for the container
1183 processes
1184 • label=type:TYPE : Set the label process type for the con‐
1186 tainer processes
1187 • label=level:LEVEL : Set the label level for the container
1189 processes
1190 • label=filetype:TYPE : Set the label file type for the con‐
1192 tainer files
1193 • label=disable : Turn off label separation for the con‐
1195 tainer
1196 • no-new-privileges : Not supported
1198 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1200 tainer
1201 • seccomp=profile.json : White listed syscalls seccomp Json
1203 file to be used as a seccomp filter
1204 --shm-size=number[unit]
1208 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1209 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1210 bytes. If the size is omitted, the default is 64m. When size is 0,
1211 there is no limit on the amount of memory used for IPC by the con‐
1212 tainer. This option conflicts with --ipc=host.
1213 --sign-by=fingerprint
1216 Sign the image using a GPG key with the specified FINGERPRINT. (This
1217 option is not available with the remote Podman client, including Mac
1218 and Windows (excluding WSL2) machines,)
1219 --skip-unused-stages
1222 Skip stages in multi-stage builds which don't affect the target stage.
1223 (Default: true).
1224 --squash
1227 Squash all of the image's new layers into a single new layer; any pre‐
1228 existing layers are not squashed.
1229 --squash-all
1232 Squash all of the new image's layers (including those inherited from a
1233 base image) into a single new layer.
1234 --ssh=default | id[=socket>
1237 SSH agent socket or keys to expose to the build. The socket path can
1238 be left empty to use the value of default=$SSH_AUTH_SOCK
1239 To later use the ssh agent, use the --mount option in a RUN instruction
1242 within a Containerfile:
1243 RUN --mount=type=ssh,id=id mycmd
1246 --stdin
1249 Pass stdin into the RUN containers. Sometime commands being RUN within
1250 a Containerfile want to request information from the user. For example
1251 apt asking for a confirmation for install. Use --stdin to be able to
1252 interact from the terminal during the build.
1253 --tag, -t=imageName
1256 Specifies the name which is assigned to the resulting image if the
1257 build process completes successfully. If imageName does not include a
1258 registry name, the registry name localhost is prepended to the image
1259 name. Can be used multiple times.
1260 --target=stageName
1263 Set the target build stage to build. When building a Containerfile
1264 with multiple build stages, --target can be used to specify an interme‐
1265 diate build stage by name as the final stage for the resulting image.
1266 Commands after the target stage is skipped.
1267 --timestamp=seconds
1270 Set the create timestamp to seconds since epoch to allow for determin‐
1271 istic builds (defaults to current time). By default, the created time‐
1272 stamp is changed and written into the image manifest with every commit,
1273 causing the image's sha256 hash to be different even if the sources are
1274 exactly the same otherwise. When --timestamp is set, the created time‐
1275 stamp is always set to the time specified and therefore not changed,
1276 allowing the image's sha256 hash to remain the same. All files commit‐
1277 ted to the layers of the image is created with the timestamp.
1278 If the only instruction in a Containerfile is FROM, this flag has no
1281 effect.
1282 --tls-verify
1285 Require HTTPS and verify certificates when contacting registries (de‐
1286 fault: true). If explicitly set to true, TLS verification is used. If
1287 set to false, TLS verification is not used. If not specified, TLS ver‐
1288 ification is used unless the target registry is listed as an insecure
1289 registry in containers-registries.conf(5)
1290 --ulimit=type=soft-limit[:hard-limit]
1293 Specifies resource limits to apply to processes launched when process‐
1294 ing RUN instructions. This option can be specified multiple times.
1295 Recognized resource types include:
1296 "core": maximum core dump size (ulimit -c)
1297 "cpu": maximum CPU time (ulimit -t)
1298 "data": maximum size of a process's data segment (ulimit -d)
1299 "fsize": maximum size of new files (ulimit -f)
1300 "locks": maximum number of file locks (ulimit -x)
1301 "memlock": maximum amount of locked memory (ulimit -l)
1302 "msgqueue": maximum amount of data in message queues (ulimit -q)
1303 "nice": niceness adjustment (nice -n, ulimit -e)
1304 "nofile": maximum number of open files (ulimit -n)
1305 "nproc": maximum number of processes (ulimit -u)
1306 "rss": maximum size of a process's (ulimit -m)
1307 "rtprio": maximum real-time scheduling priority (ulimit -r)
1308 "rttime": maximum amount of real-time execution between blocking
1309 syscalls
1310 "sigpending": maximum number of pending signals (ulimit -i)
1311 "stack": maximum stack size (ulimit -s)
1312 --unsetenv=env
1315 Unset environment variables from the final image.
1316 --unsetlabel=label
1319 Unset the image label, causing the label not to be inherited from the
1320 base image.
1321 --userns=how
1324 Sets the configuration for user namespaces when handling RUN instruc‐
1325 tions. The configured value can be "" (the empty string) or "con‐
1326 tainer" to indicate that a new user namespace is created, it can be
1327 "host" to indicate that the user namespace in which podman itself is
1328 being run is reused, or it can be the path to a user namespace which is
1329 already in use by another process.
1330 --userns-gid-map=mapping
1333 Directly specifies a GID mapping to be used to set ownership, at the
1334 filesystem level, on the working container's contents. Commands run
1335 when handling RUN instructions defaults to being run in their own user
1336 namespaces, configured using the UID and GID maps.
1337 Entries in this map take the form of one or more triples of a starting
1340 in-container GID, a corresponding starting host-level GID, and the num‐
1341 ber of consecutive IDs which the map entry represents.
1342 This option overrides the remap-gids setting in the options section of
1345 /etc/containers/storage.conf.
1346 If this option is not specified, but a global --userns-gid-map setting
1349 is supplied, settings from the global option is used.
1350 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1353 gid-map are specified, but --userns-uid-map is specified, the GID map
1354 is set to use the same numeric values as the UID map.
1355 --userns-gid-map-group=group
1358 Specifies that a GID mapping to be used to set ownership, at the
1359 filesystem level, on the working container's contents, can be found in
1360 entries in the /etc/subgid file which correspond to the specified
1361 group. Commands run when handling RUN instructions defaults to being
1362 run in their own user namespaces, configured using the UID and GID
1363 maps. If --userns-uid-map-user is specified, but --userns-gid-map-
1364 group is not specified, podman assumes that the specified user name is
1365 also a suitable group name to use as the default setting for this op‐
1366 tion.
1367 NOTE: When this option is specified by a rootless user, the specified
1370 mappings are relative to the rootless user namespace in the container,
1371 rather than being relative to the host as it is when run rootful.
1372 --userns-uid-map=mapping
1375 Directly specifies a UID mapping to be used to set ownership, at the
1376 filesystem level, on the working container's contents. Commands run
1377 when handling RUN instructions default to being run in their own user
1378 namespaces, configured using the UID and GID maps.
1379 Entries in this map take the form of one or more triples of a starting
1382 in-container UID, a corresponding starting host-level UID, and the num‐
1383 ber of consecutive IDs which the map entry represents.
1384 This option overrides the remap-uids setting in the options section of
1387 /etc/containers/storage.conf.
1388 If this option is not specified, but a global --userns-uid-map setting
1391 is supplied, settings from the global option is used.
1392 If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1395 uid-map are specified, but --userns-gid-map is specified, the UID map
1396 is set to use the same numeric values as the GID map.
1397 --userns-uid-map-user=user
1400 Specifies that a UID mapping to be used to set ownership, at the
1401 filesystem level, on the working container's contents, can be found in
1402 entries in the /etc/subuid file which correspond to the specified user.
1403 Commands run when handling RUN instructions defaults to being run in
1404 their own user namespaces, configured using the UID and GID maps. If
1405 --userns-gid-map-group is specified, but --userns-uid-map-user is not
1406 specified, podman assumes that the specified group name is also a suit‐
1407 able user name to use as the default setting for this option.
1408 NOTE: When this option is specified by a rootless user, the specified
1411 mappings are relative to the rootless user namespace in the container,
1412 rather than being relative to the host as it is when run rootful.
1413 --uts=how
1416 Sets the configuration for UTS namespaces when handling RUN instruc‐
1417 tions. The configured value can be "" (the empty string) or "con‐
1418 tainer" to indicate that a new UTS namespace to be created, or it can
1419 be "host" to indicate that the UTS namespace in which podman itself is
1420 being run is reused, or it can be the path to a UTS namespace which is
1421 already in use by another process.
1422 --variant=variant
1425 Set the architecture variant of the image to be built, and that of the
1426 base image to be pulled, if the build uses one, to the provided value
1427 instead of using the architecture variant of the build host.
1428 --volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]
1431 Create a bind mount. Specifying the -v /HOST-DIR:/CONTAINER-DIR option,
1432 Podman bind mounts /HOST-DIR from the host to /CONTAINER-DIR in the
1433 Podman container.
1434 The OPTIONS are a comma-separated list and can be: [1] ⟨#Footnote1⟩
1437 • [rw|ro]
1440 • [z|Z|O]
1442 • [U]
1444 • [[r]shared|[r]slave|[r]private]
1446 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1450 DIR must be an absolute path as well. Podman bind-mounts the HOST-DIR
1451 to the specified path. For example, when specifying the host path /foo,
1452 Podman copies the contents of /foo to the container filesystem on the
1453 host and bind mounts that into the container.
1454 You can specify multiple -v options to mount one or more mounts to a
1457 container.
1458 You can add the :ro or :rw suffix to a volume to mount it read-only or
1461 read-write mode, respectively. By default, the volumes are mounted
1462 read-write. See examples.
1463 Chowning Volume Mounts
1466 By default, Podman does not change the owner and group of source volume
1469 directories mounted. When running using user namespaces, the UID and
1470 GID inside the namespace may correspond to another UID and GID on the
1471 host.
1472 The :U suffix tells Podman to use the correct host UID and GID based on
1475 the UID and GID within the namespace, to change recursively the owner
1476 and group of the source volume.
1477 Warning use with caution since this modifies the host filesystem.
1480 Labeling Volume Mounts
1483 Labeling systems like SELinux require that proper labels are placed on
1486 volume content mounted into a container. Without a label, the security
1487 system might prevent the processes running inside the container from
1488 using the content. By default, Podman does not change the labels set by
1489 the OS.
1490 To change a label in the container context, add one of these two suf‐
1493 fixes :z or :Z to the volume mount. These suffixes tell Podman to rela‐
1494 bel file objects on the shared volumes. The z option tells Podman that
1495 two containers share the volume content. As a result, Podman labels the
1496 content with a shared content label. Shared volume labels allow all
1497 containers to read/write content. The Z option tells Podman to label
1498 the content with a private unshared label. Only the current container
1499 can use a private volume.
1500 Note: Do not relabel system files and directories. Relabeling system
1503 content might cause other confined services on the host machine to
1504 fail. For these types of containers, disabling SELinux separation is
1505 recommended. The option --security-opt label=disable disables SELinux
1506 separation for the container. For example, if a user wanted to volume
1507 mount their entire home directory into the build containers, they need
1508 to disable SELinux separation.
1509 $ podman build --security-opt label=disable -v $HOME:/home/user .
1511 Overlay Volume Mounts
1515 The :O flag tells Podman to mount the directory from the host as a tem‐
1518 porary storage using the Overlay file system. The RUN command contain‐
1519 ers are allowed to modify contents within the mountpoint and are stored
1520 in the container storage in a separate directory. In Overlay FS terms
1521 the source directory is the lower, and the container storage directory
1522 is the upper. Modifications to the mount point are destroyed when the
1523 RUN command finishes executing, similar to a tmpfs mount point.
1524 Any subsequent execution of RUN commands sees the original source di‐
1527 rectory content, any changes from previous RUN commands no longer ex‐
1528 ists.
1529 One use case of the overlay mount is sharing the package cache from the
1532 host into the container to allow speeding up builds.
1533 Note:
1536 - Overlay mounts are not currently supported in rootless mode.
1538 - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
1539 Content mounted into the container is labeled with the private label.
1543 On SELinux systems, labels in the source directory needs to be
1544 readable by the container label. If not, SELinux container separation
1545 must be disabled for the container to work.
1546 - Modification of the directory volume mounted into the container
1547 with an overlay mount can cause unexpected failures. Do not modify the
1548 directory until the container finishes running.
1549 By default bind mounted volumes are private. That means any mounts done
1552 inside containers are not be visible on the host and vice versa. This
1553 behavior can be changed by specifying a volume mount propagation prop‐
1554 erty.
1555 When the mount propagation policy is set to shared, any mounts com‐
1558 pleted inside the container on that volume is visible to both the host
1559 and container. When the mount propagation policy is set to slave, one
1560 way mount propagation is enabled and any mounts completed on the host
1561 for that volume is visible only inside of the container. To control the
1562 mount propagation property of volume use the :[r]shared, :[r]slave or
1563 :[r]private propagation flag. For mount propagation to work on the
1564 source mount point (mount point where source dir is mounted on) has to
1565 have the right propagation properties. For shared volumes, the source
1566 mount point has to be shared. And for slave volumes, the source mount
1567 has to be either shared or slave. [1] ⟨#Footnote1⟩
1568 Use df <source-dir> to determine the source mount and then use findmnt
1571 -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1572 erties of source mount, if findmnt utility is not available, the source
1573 mount point can be determined by looking at the mount entry in
1574 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1575 tion properties are specified. shared:X means the mount is shared,
1576 master:X means the mount is slave and if nothing is there that means
1577 the mount is private. [1] ⟨#Footnote1⟩
1578 To change propagation properties of a mount point use the mount com‐
1581 mand. For example, to bind mount the source directory /foo do mount
1582 --bind /foo /foo and mount --make-private --make-shared /foo. This con‐
1583 verts /foo into a shared mount point. The propagation properties of
1584 the source mount can be changed directly. For instance if / is the
1585 source mount for /foo, then use mount --make-shared / to convert / into
1586 a shared mount.
1587
1590 Build an image using local Containerfiles
1591 $ podman build .
1592 $ podman build -f Containerfile.simple .
1594 $ cat $HOME/Containerfile | podman build -f - .
1596 $ podman build -f Containerfile.simple -f Containerfile.notsosimple .
1598 $ podman build -f Containerfile.in $HOME
1600 $ podman build -t imageName .
1602 $ podman build --tls-verify=true -t imageName -f Containerfile.simple .
1604 $ podman build --tls-verify=false -t imageName .
1606 $ podman build --runtime-flag log-format=json .
1608 $ podman build --runtime-flag debug .
1610 $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .
1612 $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
1614 $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
1616 $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
1618 $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
1620 $ podman build --layers -t imageName .
1622 $ podman build --no-cache -t imageName .
1624 $ podman build --layers --force-rm -t imageName .
1626 $ podman build --no-cache --rm=false -t imageName .
1628 $ podman build --network mynet .
1630 Building a multi-architecture image using the --manifest option (requires
1634 emulation software)
1635 $ podman build --arch arm --manifest myimage /tmp/mysrc
1636 $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1638 $ podman build --arch s390x --manifest myimage /tmp/mysrc
1640 $ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
1642 $ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
1644 Building an image using a URL, Git repo, or archive
1648 The build context directory can be specified as a URL to a Container‐
1649 file, a Git repository, or URL to an archive. If the URL is a Contain‐
1650 erfile, it is downloaded to a temporary location and used as the con‐
1651 text. When a Git repository is set as the URL, the repository is cloned
1652 locally to a temporary location and then used as the context. Lastly,
1653 if the URL is an archive, it is downloaded to a temporary location and
1654 extracted before being used as the context.
1655 Building an image using a URL to a Containerfile
1658 Podman downloads the Containerfile to a temporary location and then use
1659 it as the build context.
1660 $ podman build https://10.10.10.1/podman/Containerfile
1662 Building an image using a Git repository
1666 Podman clones the specified GitHub repository to a temporary location
1667 and use it as the context. The Containerfile at the root of the reposi‐
1668 tory is used and it only works if the GitHub repository is a dedicated
1669 repository.
1670 $ podman build -t hello https://github.com/containers/PodmanHello.git
1672 $ podman run hello
1673 Note: Github does not support using git:// for performing clone opera‐
1677 tion due to recent changes in their security guidance
1678 (https://github.blog/2021-09-01-improving-git-protocol-security-
1679 github/). Use an https:// URL if the source repository is hosted on
1680 Github.
1681 Building an image using a URL to an archive
1684 Podman fetches the archive file, decompress it, and use its contents as
1685 the build context. The Containerfile at the root of the archive and the
1686 rest of the archive are used as the context of the build. Passing the
1687 -f PATH/Containerfile option as well tells the system to look for that
1688 file inside the contents of the archive.
1689 $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1691 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
1695 'identity' (no compression).
1696
1699 .containerignore/.dockerignore
1700 If the file .containerignore or .dockerignore exists in the context di‐
1701 rectory, podman build reads its contents. Use the --ignorefile option
1702 to override the Podman uses the content to exclude files and directo‐
1703 ries from the context directory, when executing COPY and ADD directives
1704 in the Containerfile/Dockerfile
1705 The .containerignore and .dockerignore files use the same syntax; if
1708 both are in the context directory, podman build only uses .containerig‐
1709 nore.
1710 Users can specify a series of Unix shell globs in a .containerignore
1713 file to identify files/directories to exclude.
1714 Podman supports a special wildcard string ** which matches any number
1717 of directories (including zero). For example, */.go excludes all files
1718 that end with .go that are found in all directories.
1719 Example .containerignore file:
1722 # exclude this content for image
1724 */*.c
1725 **/output*
1726 src
1727 */*.c Excludes files and directories whose names ends with .c in any
1731 top level subdirectory. For example, the source file include/root‐
1732 less.c.
1733 **/output* Excludes files and directories starting with output from any
1736 directory.
1737 src Excludes files named src and the directory src as well as any con‐
1740 tent in it.
1741 Lines starting with ! (exclamation mark) can be used to make exceptions
1744 to exclusions. The following is an example .containerignore file that
1745 uses this mechanism:
1746 *.doc
1748 !Help.doc
1749 Exclude all doc files except Help.doc from the image.
1753 This functionality is compatible with the handling of .containerignore
1756 files described here:
1757 https://github.com/containers/common/blob/main/docs/containerig‐
1760 nore.5.md
1761 registries.conf (/etc/containers/registries.conf)
1764 registries.conf is the configuration file which specifies which con‐
1767 tainer registries is consulted when completing image names which do not
1768 include a registry or domain portion.
1769
1772 lastlog sparse file
1773 Using a useradd command within a Containerfile with a large UID/GID
1774 creates a large sparse file /var/log/lastlog. This can cause the build
1775 to hang forever. Go language does not support sparse files correctly,
1776 which can lead to some huge files being created in the container image.
1777 When using the useradd command within the build script, pass the --no-
1780 log-init or -l option to the useradd command. This option tells user‐
1781 add to stop creating the lastlog file.
1782
1785 podman(1), buildah(1), containers-certs.d(5), containers-reg‐
1786 istries.conf(5), crun(1), runc(8), useradd(8), podman-ps(1), podman-
1787 rm(1), Containerfile(5), containerignore(5)
1788
1791 Aug 2020, Additional options and .containerignore added by Dan Walsh
1792 <dwalsh@redhat.com>
1793 May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1796 December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1799
1802 1: The Podman project is committed to inclusivity, a core value of open
1803 source. The master and slave mount propagation terminology used here is
1804 problematic and divisive, and needs to be changed. However, these
1805 terms are currently used within the Linux kernel and must be used as-is
1806 at this time. When the kernel maintainers rectify this usage, Podman
1807 will follow suit immediately.
1808 podman-build(1)