1podman-build(1)             General Commands Manual            podman-build(1)
2
3
4

NAME

6       podman-build - Build a container image using a Containerfile
7
8

SYNOPSIS

10       podman build [options] [context]
11
12
13       podman image build [options] [context]
14
15

DESCRIPTION

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
23
24       The  build  context directory can be specified as the http(s) URL of an
25       archive, git repository or Containerfile.
26
27
28       If no context directory is specified, then Podman will assume the  cur‐
29       rent  working  directory as the build context, which should contain the
30       Containerfile.
31
32
33       Containerfiles ending with a ".in"  suffix  will  be  preprocessed  via
34       CPP(1).   This  can  be useful to decompose Containerfiles into several
35       reusable parts that can be used via CPP's #include directive.   Notice,
36       a  Containerfile.in file can still be used by other tools when manually
37       preprocessing them via cpp -E.
38
39
40       When the URL is an archive, the contents of the URL is downloaded to  a
41       temporary location and extracted before execution.
42
43
44       When  the  URL is a Containerfile, the Containerfile is downloaded to a
45       temporary location.
46
47
48       When a Git repository is set as the URL, the repository is  cloned  lo‐
49       cally and then set as the context.
50
51
52       NOTE:  podman build uses code sourced from the Buildah project to build
53       container images.  This Buildah code creates Buildah containers for the
54       RUN  options in container storage. In certain situations, when the pod‐
55       man build crashes or users kill the podman build process, these  exter‐
56       nal  containers  can  be  left  in container storage. Use the podman ps
57       --all --storage command to see these  containers.  External  containers
58       can be removed with the podman rm --storage command.
59
60
61       podman  buildx  build  command  is  an  alias of podman build.  Not all
62       buildx build features are available in Podman. The buildx build  option
63       is provided for scripting compatibility.
64
65

OPTIONS

67   --add-host=host:ip
68       Add a custom host-to-IP mapping (host:ip)
69
70
71       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
72       tion can be set multiple times. Conflicts with the --no-hosts option.
73
74
75   --all-platforms
76       Instead of building for a set of platforms specified using the  --plat‐
77       form  option, inspect the build's base images, and build for all of the
78       platforms for which they are all available.  Stages that use scratch as
79       a  starting  point  can  not  be inspected, so at least one non-scratch
80       stage must be present for detection to work usefully.
81
82
83   --annotation=annotation
84       Add an image annotation (e.g. annotation=value) to the image  metadata.
85       Can be used multiple times.
86
87
88       Note: this information is not present in Docker image formats, so it is
89       discarded when writing images in Docker formats.
90
91
92   --arch=arch
93       Set the architecture of the image to be built, and that of the base im‐
94       age  to be pulled, if the build uses one, to the provided value instead
95       of using the architecture of the build host. Unless overridden,  subse‐
96       quent  lookups  of  the same image in the local storage will match this
97       architecture, regardless of  the  host.  (Examples:  arm,  arm64,  386,
98       amd64, ppc64le, s390x)
99
100
101   --authfile=path
102       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
103       ers/auth.json, which is set using podman login.  If  the  authorization
104       state  is  not found there, $HOME/.docker/config.json is checked, which
105       is set using docker login.
106
107
108       Note: There is also the option to override the default path of the  au‐
109       thentication  file  by setting the REGISTRY_AUTH_FILE environment vari‐
110       able. This can be done with export REGISTRY_AUTH_FILE=path.
111
112
113   --build-arg=arg=value
114       Specifies a build argument and its value, which will be interpolated in
115       instructions read from the Containerfiles in the same way that environ‐
116       ment variables are, but which will not be added to environment variable
117       list in the resulting image's configuration.
118
119
120   --build-context=name=value
121       Specify  an additional build context using its short name and its loca‐
122       tion.  Additional build contexts can be referenced in the  same  manner
123       as we access different stages in COPY instruction.
124
125
126       Valid values could be:
127
128
129              • Local       directory       –       e.g.       --build-context
130                project2=../path/to/project2/src (This option is not available
131                with  the  remote  Podman client. On Podman machine setup (i.e
132                macOS and Winows) path must exists on the machine VM)
133
134              • HTTP URL to a tarball – e.g. --build-context src=https://exam
135                ple.org/releases/src.tar
136
137              • Container  image – specified with a container-image:// prefix,
138                e.g.   --build-context   alpine=container-image://alpine:3.15,
139                (also accepts docker://, docker-image://)
140
141
142
143       On  the  Containerfile side, you can reference the build context on all
144       commands that accept the “from” parameter. Here’s how that might look:
145
146
147              FROM [name]
148              COPY --from=[name] ...
149              RUN --mount=from=[name] …
150
151
152
153       The value of [name] is matched with the following priority order:
154
155
156              • Named build context defined with --build-context [name]=..
157
158              • Stage defined with AS [name] inside Containerfile
159
160              • Image [name], either local or in a remote registry
161
162
163
164   --cache-from
165       Repository to utilize as a  potential  cache  source.  When  specified,
166       Buildah  will  try to look for cache images in the specified repository
167       and will attempt to pull cache images instead of actually executing the
168       build  steps  locally.  Buildah  will  only  attempt to pull previously
169       cached images if they are considered as valid cache hits.
170
171
172       Use the --cache-to option to populate a remote  repository  with  cache
173       content.
174
175
176       Example
177
178
179              # populate a cache and also consult it
180              buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
181
182
183
184       Note: --cache-from option is ignored unless --layers is specified.
185
186
187   --cache-to
188       Set this flag to specify a remote repository that will be used to store
189       cache images. Buildah will attempt to push newly built cache  image  to
190       the remote repository.
191
192
193       Note:  Use  the  --cache-from option in order to use cache content in a
194       remote repository.
195
196
197       Example
198
199
200              # populate a cache and also consult it
201              buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache .
202
203
204
205       Note: --cache-to option is ignored unless --layers is specified.
206
207
208   --cache-ttl
209       Limit the use of cached images to only  consider  images  with  created
210       timestamps  less  than  duration ago.  For example if --cache-ttl=1h is
211       specified, Buildah will only consider intermediate cache  images  which
212       are  created under the duration of one hour, and intermediate cache im‐
213       ages outside this duration will be ignored.
214
215
216       Note: Setting --cache-ttl=0 manually is equivalent to using  --no-cache
217       in  the  implementation  since this would effectively mean that user is
218       not willing to use cache at all.
219
220
221   --cap-add=CAP_xxx
222       When executing RUN instructions, run the command specified in  the  in‐
223       struction  with  the  specified capability added to its capability set.
224       Certain capabilities are granted by default; this option can be used to
225       add more.
226
227
228   --cap-drop=CAP_xxx
229       When  executing  RUN instructions, run the command specified in the in‐
230       struction with the specified capability  removed  from  its  capability
231       set.    The   CAP_CHOWN,   CAP_DAC_OVERRIDE,   CAP_FOWNER,  CAP_FSETID,
232       CAP_KILL, CAP_NET_BIND_SERVICE, CAP_SETFCAP,  CAP_SETGID,  CAP_SETPCAP,
233       CAP_SETUID,  and  CAP_SYS_CHROOT  capabilities  are granted by default;
234       this option can be used to remove them.
235
236
237       If a capability is specified to both the --cap-add and  --cap-drop  op‐
238       tions, it will be dropped, regardless of the order in which the options
239       were given.
240
241
242   --cert-dir=path
243       Use certificates at path (*.crt, *.cert, *.key) to connect to the  reg‐
244       istry.  (Default:  /etc/containers/certs.d) Please refer to containers-
245       certs.d(5) for details.  (This option is not available with the  remote
246       Podman client, including Mac and Windows (excluding WSL2) machines)
247
248
249   --cgroup-parent=path
250       Path  to  cgroups under which the cgroup for the container will be cre‐
251       ated. If the path is not absolute, the path is considered to  be  rela‐
252       tive  to  the cgroups path of the init process. Cgroups will be created
253       if they do not already exist.
254
255
256   --cgroupns=how
257       Sets the configuration for cgroup namespaces when handling RUN instruc‐
258       tions.   The configured value can be "" (the empty string) or "private"
259       to indicate that a new cgroup namespace should be created, or it can be
260       "host" to indicate that the cgroup namespace in which buildah itself is
261       being run should be reused.
262
263
264   --compress
265       This option is added to be aligned with other containers CLIs.   Podman
266       doesn't  communicate with a daemon or a remote server.  Thus, compress‐
267       ing the data before sending it is irrelevant to Podman. (This option is
268       not  available with the remote Podman client, including Mac and Windows
269       (excluding WSL2) machines)
270
271
272   --cpp-flag=flags
273       Set additional flags to pass to the C Preprocessor  cpp(1).  Container‐
274       files  ending with a ".in" suffix will be preprocessed via cpp(1). This
275       option can be used to pass additional flags to cpp.Note: You  can  also
276       set  default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment vari‐
277       able (e.g., export BUILDAH_CPPFLAGS="-DDEBUG").
278
279
280   --cpu-period=limit
281       Set the CPU period for the Completely Fair Scheduler (CFS), which is  a
282       duration in microseconds. Once the container's CPU quota is used up, it
283       will not be scheduled to run until the current period ends. Defaults to
284       100000 microseconds.
285
286
287       On  some  systems,  changing the resource limits may not be allowed for
288       non-root  users.  For  more  details,  see  https://github.com/contain
289       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
290       source-limits-fails-with-a-permissions-error
291
292
293       This option is not supported on cgroups V1 rootless systems.
294
295
296   --cpu-quota=limit
297       Limit the CPU Completely Fair Scheduler (CFS) quota.
298
299
300       Limit the container's CPU usage. By default, containers  run  with  the
301       full  CPU  resource. The limit is a number in microseconds. If a number
302       is provided, the container will be allowed to use that  much  CPU  time
303       until the CPU period ends (controllable via --cpu-period).
304
305
306       On  some  systems,  changing the resource limits may not be allowed for
307       non-root  users.  For  more  details,  see  https://github.com/contain
308       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
309       source-limits-fails-with-a-permissions-error
310
311
312       This option is not supported on cgroups V1 rootless systems.
313
314
315   --cpu-shares, -c=shares
316       CPU shares (relative weight).
317
318
319       By default, all containers get the same proportion of CPU cycles.  This
320       proportion  can  be  modified  by  changing  the  container's CPU share
321       weighting relative to the combined weight of all the  running  contain‐
322       ers.  Default weight is 1024.
323
324
325       The  proportion  will  only apply when CPU-intensive processes are run‐
326       ning.  When tasks in one container are idle, other containers  can  use
327       the left-over CPU time. The actual amount of CPU time will vary depend‐
328       ing on the number of containers running on the system.
329
330
331       For example, consider three containers, one has a cpu-share of 1024 and
332       two others have a cpu-share setting of 512. When processes in all three
333       containers attempt to use 100% of CPU, the first  container  would  re‐
334       ceive  50% of the total CPU time. If a fourth container is added with a
335       cpu-share of 1024, the first container only gets 33% of  the  CPU.  The
336       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
337
338
339       On a multi-core system, the shares of CPU time are distributed over all
340       CPU cores. Even if a container is limited to  less  than  100%  of  CPU
341       time, it can use 100% of each individual CPU core.
342
343
344       For example, consider a system with more than three cores.  If the con‐
345       tainer C0 is started with --cpu-shares=512 running one process, and an‐
346       other  container  C1 with --cpu-shares=1024 running two processes, this
347       can result in the following division of CPU shares:
348
349
350       ┌────┬───────────┬─────┬──────────────┐
351PID container CPU CPU share    
352       ├────┼───────────┼─────┼──────────────┤
353       │100 │ C0        │ 0   │ 100% of CPU0 │
354       ├────┼───────────┼─────┼──────────────┤
355       │101 │ C1        │ 1   │ 100% of CPU1 │
356       ├────┼───────────┼─────┼──────────────┤
357       │102 │ C1        │ 2   │ 100% of CPU2 │
358       └────┴───────────┴─────┴──────────────┘
359
360       On some systems, changing the resource limits may not  be  allowed  for
361       non-root  users.  For  more  details,  see  https://github.com/contain
362       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
363       source-limits-fails-with-a-permissions-error
364
365
366       This option is not supported on cgroups V1 rootless systems.
367
368
369   --cpuset-cpus=number
370       CPUs in which to allow execution. Can be specified as a comma-separated
371       list (e.g. 0,1), as a range (e.g.  0-3),  or  any  combination  thereof
372       (e.g. 0-3,7,11-15).
373
374
375       On  some  systems,  changing the resource limits may not be allowed for
376       non-root  users.  For  more  details,  see  https://github.com/contain
377       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
378       source-limits-fails-with-a-permissions-error
379
380
381       This option is not supported on cgroups V1 rootless systems.
382
383
384   --cpuset-mems=nodes
385       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
386       tive on NUMA systems.
387
388
389       If  there  are  four  memory  nodes  on the system (0-3), use --cpuset-
390       mems=0,1 then processes in the container will only use memory from  the
391       first two memory nodes.
392
393
394       On  some  systems,  changing the resource limits may not be allowed for
395       non-root  users.  For  more  details,  see  https://github.com/contain
396       ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
397       source-limits-fails-with-a-permissions-error
398
399
400       This option is not supported on cgroups V1 rootless systems.
401
402
403   --creds=[username[:password]]
404       The [username[:password]] to use to authenticate with the registry,  if
405       required.   If  one  or  both  values  are not supplied, a command line
406       prompt will appear and the value can be entered. The  password  is  en‐
407       tered without echo.
408
409
410   --decryption-key=key[:passphrase]
411       The  [key[:passphrase]]  to  be  used for decryption of images. Key can
412       point to keys and/or certificates. Decryption will be  tried  with  all
413       keys.  If  the  key  is protected by a passphrase, it is required to be
414       passed in the argument and omitted otherwise.
415
416
417   --device=host-device[:container-device][:permissions]
418       Add a host device to the container. Optional permissions parameter  can
419       be  used  to  specify device permissions by combining r for read, w for
420       write, and m for mknod(2).
421
422
423       Example: --device=/dev/sdc:/dev/xvdc:rwm.
424
425
426       Note: if host-device is a symbolic link then it will be resolved first.
427       The  container  will only store the major and minor numbers of the host
428       device.
429
430
431       Podman may load kernel modules required for using the specified device.
432       The  devices  that  Podman  will  load  modules for when necessary are:
433       /dev/fuse.
434
435
436       In rootless mode, the new device is bind mounted in the container  from
437       the host rather than Podman creating it within the container space. Be‐
438       cause the bind mount retains its SELinux label on SELinux systems,  the
439       container  can get permission denied when accessing the mounted device.
440       Modify SELinux settings to allow containers to use  all  device  labels
441       via the following command:
442
443
444       $ sudo setsebool -P  container_use_devices=true
445
446
447       Note: if the user only has access rights via a group, accessing the de‐
448       vice from inside a rootless container will fail.  The  crun(1)  runtime
449       offers  a  workaround  for  this  by  adding  the  option  --annotation
450       run.oci.keep_original_groups=1.
451
452
453   --disable-compression, -D
454       Don't compress filesystem layers when building the image unless  it  is
455       required by the location where the image is being written.  This is the
456       default setting, because image layers are compressed automatically when
457       they  are pushed to registries, and images being written to local stor‐
458       age would only need to be decompressed again to be stored.  Compression
459       can be forced in all cases by specifying --disable-compression=false.
460
461
462   --disable-content-trust
463       This  is  a  Docker-specific  option to disable image verification to a
464       container registry and is not supported by Podman.  This  option  is  a
465       NOOP and provided solely for scripting compatibility.
466
467
468   --dns=ipaddr
469       Set custom DNS servers.
470
471
472       This option can be used to override the DNS configuration passed to the
473       container. Typically this is necessary when the host DNS  configuration
474       is  invalid  for the container (e.g., 127.0.0.1). When this is the case
475       the --dns flag is necessary for every run.
476
477
478       The special value none can be specified to disable creation of /etc/re‐
479       solv.conf in the container by Podman.  The /etc/resolv.conf file in the
480       image will be used without changes.
481
482
483       This option cannot be combined with --network that is set to none.
484
485
486       Note: this option takes effect only  during  RUN  instructions  in  the
487       build.  It does not affect /etc/resolv.conf in the final image.
488
489
490   --dns-option=option
491       Set custom DNS options to be used during the build.
492
493
494   --dns-search=domain
495       Set custom DNS search domains to be used during the build.
496
497
498   --env=env[=value]
499       Add  a value (e.g. env=value) to the built image.  Can be used multiple
500       times.  If neither = nor a *value* are specified, but env is set in the
501       current  environment,  the  value  from the current environment will be
502       added to the image.  To remove an environment variable from  the  built
503       image, use the --unsetenv option.
504
505
506   --file, -f=Containerfile
507       Specifies  a Containerfile which contains instructions for building the
508       image, either a local file or an http or https URL.  If more  than  one
509       Containerfile  is  specified,  FROM  instructions will only be accepted
510       from the first specified file.
511
512
513       If a build context is not specified, and at least one Containerfile  is
514       a  local  file,  the  directory in which it resides will be used as the
515       build context.
516
517
518       If you specify -f -, the  Containerfile  contents  will  be  read  from
519       stdin.
520
521
522   --force-rm
523       Always  remove intermediate containers after a build, even if the build
524       fails (default true).
525
526
527   --format
528       Control the format for the built  image's  manifest  and  configuration
529       data.   Recognized  formats  include  oci (OCI image-spec v1.0, the de‐
530       fault) and docker (version 2, using schema format 2 for the manifest).
531
532
533       Note: You can also override the default format  by  setting  the  BUIL‐
534       DAH_FORMAT environment variable.  export BUILDAH_FORMAT=docker
535
536
537   --from
538       Overrides  the  first  FROM  instruction  within the Containerfile.  If
539       there are multiple FROM instructions in a Containerfile, only the first
540       is changed.
541
542
543       With  the  remote podman client, not all container transports will work
544       as expected. For example, oci-archive:/x.tar will reference  /x.tar  on
545       the remote machine instead of on the client. If you need to support re‐
546       mote podman clients, it is best to  restrict  yourself  to  containers-
547       storage: and docker:// transports.
548
549
550   --help, -h
551       Print usage statement
552
553
554   --hooks-dir=path
555       Each  *.json  file in the path configures a hook for buildah build con‐
556       tainers. For more details on the syntax of the JSON files and  the  se‐
557       mantics of hook injection. Buildah currently support both the 1.0.0 and
558       0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
559
560
561       This option may be set multiple times; paths from  later  options  have
562       higher precedence.
563
564
565       For  the annotation conditions, buildah uses any annotations set in the
566       generated OCI configuration.
567
568
569       For the bind-mount conditions, only mounts explicitly requested by  the
570       caller via --volume are considered. Bind mounts that buildah inserts by
571       default (e.g. /dev/shm) are not considered.
572
573
574       If --hooks-dir is unset for root callers, Buildah  will  currently  de‐
575       fault    to    /usr/share/containers/oci/hooks.d    and   /etc/contain‐
576       ers/oci/hooks.d in order of increasing precedence. Using these defaults
577       is  deprecated,  and  callers  should  migrate  to  explicitly  setting
578       --hooks-dir.
579
580
581   --http-proxy
582       Pass through HTTP Proxy environment variables.
583
584
585   --identity-label
586       Adds default identity label io.buildah.version if set. (default true).
587
588
589   --ignorefile
590       Path to an alternative .containerignore file.
591
592
593   --iidfile=ImageIDfile
594       Write the built image's ID to the file.  When --platform  is  specified
595       more than once, attempting to use this option will trigger an error.
596
597
598   --ipc=how
599       Sets  the  configuration  for IPC namespaces when handling RUN instruc‐
600       tions.  The configured value can be ""  (the  empty  string)  or  "con‐
601       tainer"  to  indicate that a new IPC namespace should be created, or it
602       can be "host" to indicate that the IPC namespace in which podman itself
603       is  being  run  should be reused, or it can be the path to an IPC name‐
604       space which is already in use by another process.
605
606
607   --isolation=type
608       Controls what type of isolation is used for running processes  as  part
609       of RUN instructions.  Recognized types include oci (OCI-compatible run‐
610       time, the default), rootless (OCI-compatible runtime  invoked  using  a
611       modified  configuration  and  its --rootless option enabled, with --no-
612       new-keyring --no-pivot added to its create invocation, with network and
613       UTS namespaces disabled, and IPC, PID, and user namespaces enabled; the
614       default for unprivileged users), and chroot (an internal  wrapper  that
615       leans more toward chroot(1) than container technology).
616
617
618       Note:  You  can also override the default isolation type by setting the
619       BUILDAH_ISOLATION environment variable.  export BUILDAH_ISOLATION=oci
620
621
622   --jobs=number
623       Run up to N concurrent stages in parallel.  If the number  of  jobs  is
624       greater  than 1, stdin will be read from /dev/null.  If 0 is specified,
625       then there is no limit in the number of jobs that run in parallel.
626
627
628   --label=label
629       Add an image label (e.g. label=value) to the  image  metadata.  Can  be
630       used multiple times.
631
632
633       Users can set a special LABEL io.containers.capabilities=CAP1,CAP2,CAP3
634       in a Containerfile that specifies the list of  Linux  capabilities  re‐
635       quired  for  the  container  to run properly. This label specified in a
636       container image tells Podman to run the container with just these capa‐
637       bilities.  Podman  launches the container with just the specified capa‐
638       bilities, as long as this list of capabilities is a subset of  the  de‐
639       fault list.
640
641
642       If  the  specified capabilities are not in the default set, Podman will
643       print an error message and will run the container with the default  ca‐
644       pabilities.
645
646
647   --layers
648       Cache intermediate images during the build process (Default is true).
649
650
651       Note:  You can also override the default value of layers by setting the
652       BUILDAH_LAYERS environment variable. export BUILDAH_LAYERS=true
653
654
655   --logfile=filename
656       Log output which would be sent to standard output and standard error to
657       the  specified  file  instead of to standard output and standard error.
658       This option is not supported on the remote client,  including  Mac  and
659       Windows (excluding WSL2) machines.
660
661
662   --logsplit=bool-value
663       If --logfile and --platform are specified, the --logsplit option allows
664       end-users to split the log file for each platform into different  files
665       in  the  following  format: ${logfile}_${platform-os}_${platform-arch}.
666       This option is not supported on the remote client,  including  Mac  and
667       Windows (excluding WSL2) machines.
668
669
670   --manifest=manifest
671       Name of the manifest list to which the image will be added. Creates the
672       manifest list if it does not exist. This option is useful for  building
673       multi architecture images.
674
675
676   --memory, -m=number[unit]
677       Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
678       g (gibibytes).
679
680
681       Allows the memory available to a container to be  constrained.  If  the
682       host  supports  swap  memory,  then the -m memory setting can be larger
683       than physical RAM. If a limit of 0 is specified  (not  using  -m),  the
684       container's  memory  is not limited. The actual limit may be rounded up
685       to a multiple of the operating system's page size (the value  would  be
686       very large, that's millions of trillions).
687
688
689       This option is not supported on cgroups V1 rootless systems.
690
691
692   --memory-swap=number[unit]
693       A  limit  value  equal to memory plus swap.  A unit can be b (bytes), k
694       (kibibytes), m (mebibytes), or g (gibibytes).
695
696
697       Must be used with the -m (--memory) flag.  The  argument  value  should
698       always be larger than that of
699        -m (--memory) By default, it is set to double the value of --memory.
700
701
702       Set number to -1 to enable unlimited swap.
703
704
705       This option is not supported on cgroups V1 rootless systems.
706
707
708   --network=mode, --net
709       Sets  the  configuration  for  network namespaces when handling RUN in‐
710       structions.
711
712
713       Valid mode values are:
714
715
716none: no networking.
717
718host: use the Podman host network stack. Note: the  host  mode
719                gives  the container full access to local system services such
720                as D-bus and is therefore considered insecure.
721
722ns:path: path to a network namespace to join.
723
724private: create a new namespace for the container (default)
725
726<network name|ID>: Join the network with the given name or ID,
727                e.g.  use  --network  mynet  to join the network with the name
728                mynet. Only supported for rootful users.
729
730
731
732   --no-cache
733       Do not use existing cached images for the container build.  Build  from
734       the start with a new set of cached layers.
735
736
737   --no-hosts
738       Do  not  create  /etc/hosts for the container.  By default, Podman will
739       manage /etc/hosts, adding the container's own IP address and any  hosts
740       from  --add-host.  --no-hosts disables this, and the image's /etc/hosts
741       will be preserved unmodified.
742
743
744       This option conflicts with --add-host.
745
746
747   --omit-history
748       Omit build history information in the built image. (default false).
749
750
751       This option is useful for the cases where end users explicitly want  to
752       set  --omit-history  to  omit the optional History from built images or
753       when working with images built using build tools that  do  not  include
754       History information in their images.
755
756
757   --os=string
758       Set  the  OS of the image to be built, and that of the base image to be
759       pulled, if the build uses one, instead of using the  current  operating
760       system  of the build host. Unless overridden, subsequent lookups of the
761       same image in the local storage will match this OS, regardless  of  the
762       host.
763
764
765   --os-feature=feature
766       Set the name of a required operating system feature for the image which
767       will be built.  By default, if the image is not based on  scratch,  the
768       base image's required OS feature list is kept, if the base image speci‐
769       fied any.  This option is typically only meaningful when the image's OS
770       is Windows.
771
772
773       If  feature  has a trailing -, then the feature is removed from the set
774       of required features which will be listed in the image.
775
776
777   --os-version=version
778       Set the exact required operating system version  for  the  image  which
779       will  be  built.  By default, if the image is not based on scratch, the
780       base image's required OS version is kept, if the base  image  specified
781       one.   This  option is typically only meaningful when the image's OS is
782       Windows, and is typically set in Windows base images, so using this op‐
783       tion is usually unnecessary.
784
785
786   --output, -o=output-opts
787       Output destination (format: type=local,dest=path)
788
789
790       The  --output (or -o) option extends the default behavior of building a
791       container image by allowing users to export the contents of  the  image
792       as  files  on  the local filesystem, which can be useful for generating
793       local binaries, code generation, etc. (This  option  is  not  available
794       with  the  remote  Podman  client, including Mac and Windows (excluding
795       WSL2) machines)
796
797
798       The value for --output  is  a  comma-separated  sequence  of  key=value
799       pairs, defining the output type and options.
800
801
802       Supported keys are: - dest: Destination path for exported output. Valid
803       value is absolute or relative path, - means  the  standard  output.   -
804       type: Defines the type of output to be used. Valid values is documented
805       below.
806
807
808       Valid type values are: - local: write the resulting build  files  to  a
809       directory  on  the  client-side.  - tar: write the resulting files as a
810       single tarball (.tar).
811
812
813       If no type is specified, the value defaults to  local.   Alternatively,
814       instead  of  a  comma-separated  sequence, the value of --output can be
815       just  a  destination  (in  the  **dest**  format)  (e.g.--output  some-
816       path,--output -) where--output some-pathis treated as if **type=local**
817       and--output -` is treated as if type=tar.
818
819
820   --pid=pid
821       Sets the configuration for PID namespaces when  handling  RUN  instruc‐
822       tions.   The  configured  value  can  be "" (the empty string) or "con‐
823       tainer" to indicate that a new PID namespace should be created,  or  it
824       can be "host" to indicate that the PID namespace in which podman itself
825       is being run should be reused, or it can be the path to a PID namespace
826       which is already in use by another process.
827
828
829   --platform=os/arch[/variant][,...]
830       Set  the  os/arch of the built image (and its base image, if your build
831       uses one) to the provided value instead of using the current  operating
832       system  and  architecture  of the host (for example linux/arm).  Unless
833       overridden, subsequent lookups of the same image in the  local  storage
834       will match this platform, regardless of the host.
835
836
837       If  --platform is set, then the values of the --arch, --os, and --vari‐
838       ant options will be overridden.
839
840
841       The --platform option can be specified  more  than  once,  or  given  a
842       comma-separated  list  of  values  as its argument.  When more than one
843       platform is specified, the --manifest option should be used instead  of
844       the --tag option.
845
846
847       Os/arch  pairs  are those used by the Go Programming Language.  In sev‐
848       eral cases the arch value for a platform differs from one  produced  by
849       other  tools  such as the arch command.  Valid OS and architecture name
850       combinations  are  listed  as  values  for   $GOOS   and   $GOARCH   at
851       https://golang.org/doc/install/source#environment,   and  can  also  be
852       found by running go tool dist list.
853
854
855       While podman build is happy to use base images and build images for any
856       platform  that  exists,  RUN  instructions  will not be able to succeed
857       without the help of emulation  provided  by  packages  like  qemu-user-
858       static.
859
860
861   --pull=policy
862       Pull image policy. The default is always.
863
864
865always,  true: Always pull the image and throw an error if the
866                pull fails.
867
868missing: Pull the image only if it could not be found  in  the
869                local containers storage.  Throw an error if no image could be
870                found and the pull fails.
871
872never, false: Never pull the image but use the  one  from  the
873                local containers storage.  Throw an error if no image could be
874                found.
875
876newer: Pull if the image on the registry is newer than the one
877                in the local containers storage.  An image is considered to be
878                newer when the digests  are  different.   Comparing  the  time
879                stamps  is  prone  to errors.  Pull errors are suppressed if a
880                local image was found.
881
882
883
884   --quiet, -q
885       Suppress output messages which indicate which instruction is being pro‐
886       cessed,  and  of progress when pulling images from a registry, and when
887       writing the output image.
888
889
890   --retry=attempts
891       Number of times to retry in case of failure when performing pull of im‐
892       ages from registry. Default is 3.
893
894
895   --retry-delay=duration
896       Duration  of  delay between retry attempts in case of failure when per‐
897       forming pull of images from registry. Default is 2s.
898
899
900   --rm
901       Remove intermediate containers after a successful build (default true).
902
903
904   --runtime=path
905       The path to an alternate OCI-compatible runtime, which will be used  to
906       run commands specified by the RUN instruction.
907
908
909       Note:  You  can  also override the default runtime by setting the BUIL‐
910       DAH_RUNTIME  environment  variable.   export   BUILDAH_RUNTIME=/usr/lo‐
911       cal/bin/runc
912
913
914   --runtime-flag=flag
915       Adds  global  flags  for  the  container  rutime. To list the supported
916       flags, please consult the manpages of the selected container runtime.
917
918
919       Note: Do not pass the leading -- to the flag. To  pass  the  runc  flag
920       --log-format  json  to  buildah build, the option given would be --run‐
921       time-flag log-format=json.
922
923
924   --secret=id=id,src=path
925       Pass secret information to be used in the  Containerfile  for  building
926       images in a safe way that will not end up stored in the final image, or
927       be seen in other stages.  The secret will be mounted in  the  container
928       at the default location of /run/secrets/id.
929
930
931       To  later  use  the secret, use the --mount option in a RUN instruction
932       within a Containerfile:
933
934
935       RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
936
937
938   --security-opt=option
939       Security Options
940
941
942apparmor=unconfined : Turn off apparmor  confinement  for  the
943                container
944
945apparmor=your-profile  :  Set the apparmor confinement profile
946                for the container
947
948label=user:USER     : Set the label  user  for  the  container
949                processes
950
951label=role:ROLE      :  Set  the  label role for the container
952                processes
953
954label=type:TYPE     : Set the label process type for the  con‐
955                tainer processes
956
957label=level:LEVEL    :  Set  the label level for the container
958                processes
959
960label=filetype:TYPE : Set the label file  type  for  the  con‐
961                tainer files
962
963label=disable        :  Turn off label separation for the con‐
964                tainer
965
966no-new-privileges   : Not supported
967
968seccomp=unconfined : Turn off seccomp confinement for the con‐
969                tainer
970
971seccomp=profile.json  :   White  listed  syscalls seccomp Json
972                file to be used as a seccomp filter
973
974
975
976   --shm-size=number[unit]
977       Size  of  /dev/shm.  A  unit  can  be  b  (bytes),  k  (kibibytes),   m
978       (mebibytes), or g (gibibytes).  If the unit is omitted, the system uses
979       bytes. If the size is omitted, the default is 64m.   When  size  is  0,
980       there  is  no  limit  on  the amount of memory used for IPC by the con‐
981       tainer.  This option conflicts with --ipc=host.
982
983
984   --sign-by=fingerprint
985       Sign the image using a GPG key with the  specified  FINGERPRINT.  (This
986       option  is  not  available with the remote Podman client, including Mac
987       and Windows (excluding WSL2) machines,)
988
989
990   --skip-unused-stages
991       Skip stages in multi-stage builds which don't affect the target  stage.
992       (Default: true).
993
994
995   --squash
996       Squash  all of the image's new layers into a single new layer; any pre‐
997       existing layers are not squashed.
998
999
1000   --squash-all
1001       Squash all of the new image's layers (including those inherited from  a
1002       base image) into a single new layer.
1003
1004
1005   --ssh=default | id[=socket>
1006       SSH  agent  socket or keys to expose to the build.  The socket path can
1007       be left empty to use the value of default=$SSH_AUTH_SOCK
1008
1009
1010       To later use the ssh agent, use the --mount option in a RUN instruction
1011       within a Containerfile:
1012
1013
1014       RUN --mount=type=ssh,id=id mycmd
1015
1016
1017   --stdin
1018       Pass  stdin into the RUN containers. Sometime commands being RUN within
1019       a Containerfile want to request information from the user. For  example
1020       apt  asking  for a confirmation for install.  Use --stdin to be able to
1021       interact from the terminal during the build.
1022
1023
1024   --tag, -t=imageName
1025       Specifies the name which will be assigned to the resulting image if the
1026       build  process completes successfully.  If imageName does not include a
1027       registry name, the registry name localhost will be prepended to the im‐
1028       age name.
1029
1030
1031   --target=stageName
1032       Set  the  target  build  stage to build.  When building a Containerfile
1033       with multiple build stages, --target can be used to specify an interme‐
1034       diate  build  stage by name as the final stage for the resulting image.
1035       Commands after the target stage will be skipped.
1036
1037
1038   --timestamp=seconds
1039       Set the create timestamp to seconds since epoch to allow for  determin‐
1040       istic  builds (defaults to current time). By default, the created time‐
1041       stamp is changed and written into the image manifest with every commit,
1042       causing the image's sha256 hash to be different even if the sources are
1043       exactly the same otherwise.  When --timestamp is set, the created time‐
1044       stamp  is  always  set to the time specified and therefore not changed,
1045       allowing the image's sha256 hash to remain the same. All files  commit‐
1046       ted to the layers of the image will be created with the timestamp.
1047
1048
1049       If  the  only  instruction in a Containerfile is FROM, this flag has no
1050       effect.
1051
1052
1053   --tls-verify
1054       Require HTTPS and verify certificates when contacting  registries  (de‐
1055       fault:  true).   If  explicitly  set  to true, TLS verification will be
1056       used.  If set to false, TLS verification will  not  be  used.   If  not
1057       specified,  TLS verification will be used unless the target registry is
1058       listed as an insecure registry in containers-registries.conf(5)
1059
1060
1061   --ulimit=type=soft-limit[:hard-limit]
1062       Specifies resource limits to apply to processes launched when  process‐
1063       ing  RUN  instructions.  This  option  can be specified multiple times.
1064       Recognized resource types include:
1065         "core": maximum core dump size (ulimit -c)
1066         "cpu": maximum CPU time (ulimit -t)
1067         "data": maximum size of a process's data segment (ulimit -d)
1068         "fsize": maximum size of new files (ulimit -f)
1069         "locks": maximum number of file locks (ulimit -x)
1070         "memlock": maximum amount of locked memory (ulimit -l)
1071         "msgqueue": maximum amount of data in message queues (ulimit -q)
1072         "nice": niceness adjustment (nice -n, ulimit -e)
1073         "nofile": maximum number of open files (ulimit -n)
1074         "nproc": maximum number of processes (ulimit -u)
1075         "rss": maximum size of a process's (ulimit -m)
1076         "rtprio": maximum real-time scheduling priority (ulimit -r)
1077         "rttime": maximum amount  of  real-time  execution  between  blocking
1078       syscalls
1079         "sigpending": maximum number of pending signals (ulimit -i)
1080         "stack": maximum stack size (ulimit -s)
1081
1082
1083   --unsetenv=env
1084       Unset environment variables from the final image.
1085
1086
1087   --userns=how
1088       Sets  the  configuration for user namespaces when handling RUN instruc‐
1089       tions.  The configured value can be ""  (the  empty  string)  or  "con‐
1090       tainer" to indicate that a new user namespace should be created, it can
1091       be "host" to indicate that the user namespace in which podman itself is
1092       being  run  should be reused, or it can be the path to a user namespace
1093       which is already in use by another process.
1094
1095
1096   --userns-gid-map=mapping
1097       Directly specifies a GID mapping which should be used to set ownership,
1098       at the filesystem level, on the working container's contents.  Commands
1099       run when handling RUN instructions will default to being run  in  their
1100       own user namespaces, configured using the UID and GID maps.
1101
1102
1103       Entries  in this map take the form of one or more triples of a starting
1104       in-container GID, a corresponding starting host-level GID, and the num‐
1105       ber of consecutive IDs which the map entry represents.
1106
1107
1108       This  option overrides the remap-gids setting in the options section of
1109       /etc/containers/storage.conf.
1110
1111
1112       If this option is not specified, but a global --userns-gid-map  setting
1113       is supplied, settings from the global option will be used.
1114
1115
1116       If  none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
1117       gid-map are specified, but --userns-uid-map is specified, the  GID  map
1118       will be set to use the same numeric values as the UID map.
1119
1120
1121   --userns-gid-map-group=group
1122       Specifies  that a GID mapping which should be used to set ownership, at
1123       the filesystem level, on the working container's contents, can be found
1124       in  entries  in  the /etc/subgid file which correspond to the specified
1125       group.  Commands run when handling RUN instructions will default to be‐
1126       ing  run in their own user namespaces, configured using the UID and GID
1127       maps.  If --userns-uid-map-user  is  specified,  but  --userns-gid-map-
1128       group is not specified, podman will assume that the specified user name
1129       is also a suitable group name to use as the default  setting  for  this
1130       option.
1131
1132
1133       NOTE:  When  this option is specified by a rootless user, the specified
1134       mappings are relative to the rootless user namespace in the  container,
1135       rather than being relative to the host as it would be when run rootful.
1136
1137
1138   --userns-uid-map=mapping
1139       Directly specifies a UID mapping which should be used to set ownership,
1140       at the filesystem level, on the working container's contents.  Commands
1141       run  when  handling RUN instructions will default to being run in their
1142       own user namespaces, configured using the UID and GID maps.
1143
1144
1145       Entries in this map take the form of one or more triples of a  starting
1146       in-container UID, a corresponding starting host-level UID, and the num‐
1147       ber of consecutive IDs which the map entry represents.
1148
1149
1150       This option overrides the remap-uids setting in the options section  of
1151       /etc/containers/storage.conf.
1152
1153
1154       If  this option is not specified, but a global --userns-uid-map setting
1155       is supplied, settings from the global option will be used.
1156
1157
1158       If none of --userns-uid-map-user, --userns-gid-map-group, or  --userns-
1159       uid-map  are  specified, but --userns-gid-map is specified, the UID map
1160       will be set to use the same numeric values as the GID map.
1161
1162
1163   --userns-uid-map-user=user
1164       Specifies that a UID mapping which should be used to set ownership,  at
1165       the filesystem level, on the working container's contents, can be found
1166       in entries in the /etc/subuid file which correspond  to  the  specified
1167       user.   Commands run when handling RUN instructions will default to be‐
1168       ing run in their own user namespaces, configured using the UID and  GID
1169       maps.   If  --userns-gid-map-group  is specified, but --userns-uid-map-
1170       user is not specified, podman will assume that the specified group name
1171       is also a suitable user name to use as the default setting for this op‐
1172       tion.
1173
1174
1175       NOTE: When this option is specified by a rootless user,  the  specified
1176       mappings  are relative to the rootless user namespace in the container,
1177       rather than being relative to the host as it would be when run rootful.
1178
1179
1180   --uts=how
1181       Sets the configuration for UTS namespaces when  handling  RUN  instruc‐
1182       tions.   The  configured  value  can  be "" (the empty string) or "con‐
1183       tainer" to indicate that a new UTS namespace should be created,  or  it
1184       can be "host" to indicate that the UTS namespace in which podman itself
1185       is being run should be reused, or it can be the path to a UTS namespace
1186       which is already in use by another process.
1187
1188
1189   --variant=variant
1190       Set  the architecture variant of the image to be built, and that of the
1191       base image to be pulled, if the build uses one, to the  provided  value
1192       instead of using the architecture variant of the build host.
1193
1194
1195   --volume, -v=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]
1196       Create a bind mount. If you specify -v /HOST-DIR:/CONTAINER-DIR, Podman
1197       bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Podman  con‐
1198       tainer.  (This  option  is not available with the remote Podman client,
1199       including Mac and Windows (excluding WSL2) machines)
1200
1201
1202       The OPTIONS are a comma-separated list and can be: [1] ⟨#Footnote1⟩
1203
1204
1205              • [rw|ro]
1206
1207              • [z|Z|O]
1208
1209              • [U]
1210
1211              • [[r]shared|[r]slave|[r]private]
1212
1213
1214
1215       The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1216       DIR  must  be an absolute path as well. Podman bind-mounts the HOST-DIR
1217       to the path you specify. For example, if you supply /foo  as  the  host
1218       path, Podman copies the contents of /foo to the container filesystem on
1219       the host and bind mounts that into the container.
1220
1221
1222       You can specify multiple  -v options to mount one or more mounts  to  a
1223       container.
1224
1225
1226       You  can add the :ro or :rw suffix to a volume to mount it read-only or
1227       read-write mode, respectively. By  default,  the  volumes  are  mounted
1228       read-write.  See examples.
1229
1230
1231       Chowning Volume Mounts
1232
1233
1234       By default, Podman does not change the owner and group of source volume
1235       directories mounted. When running using user namespaces,  the  UID  and
1236       GID  inside  the namespace may correspond to another UID and GID on the
1237       host.
1238
1239
1240       The :U suffix tells Podman to use the correct host UID and GID based on
1241       the  UID  and GID within the namespace, to change recursively the owner
1242       and group of the source volume.
1243
1244
1245       Warning use with caution since this will modify the host filesystem.
1246
1247
1248       Labeling Volume Mounts
1249
1250
1251       Labeling systems like SELinux require that proper labels are placed  on
1252       volume  content mounted into a container. Without a label, the security
1253       system might prevent the processes running inside  the  container  from
1254       using the content. By default, Podman does not change the labels set by
1255       the OS.
1256
1257
1258       To change a label in the container context, you can add either  of  two
1259       suffixes  :z  or  :Z to the volume mount. These suffixes tell Podman to
1260       relabel file objects on the shared volumes. The z option  tells  Podman
1261       that  two  containers share the volume content. As a result, Podman la‐
1262       bels the content with a shared content label. Shared volume labels  al‐
1263       low all containers to read/write content.  The Z option tells Podman to
1264       label the content with a private unshared label.  Only the current con‐
1265       tainer can use a private volume.
1266
1267
1268       Note:  Do  not  relabel system files and directories. Relabeling system
1269       content might cause other confined services on your  machine  to  fail.
1270       For  these  types of containers, disabling SELinux separation is recom‐
1271       mended.  The option --security-opt label=disable disables SELinux sepa‐
1272       ration  for  the  container.   For  example, if a user wanted to volume
1273       mount their entire home directory into the build containers, they  need
1274       to disable SELinux separation.
1275
1276
1277                 $ podman build --security-opt label=disable -v $HOME:/home/user .
1278
1279
1280
1281       Overlay Volume Mounts
1282
1283
1284       The :O flag tells Podman to mount the directory from the host as a tem‐
1285       porary storage using the Overlay file system. The RUN command  contain‐
1286       ers are allowed to modify contents within the mountpoint and are stored
1287       in the container storage in a separate directory.  In Overlay FS  terms
1288       the  source  directory will be the lower, and the container storage di‐
1289       rectory will be the upper. Modifications to the  mount  point  are  de‐
1290       stroyed  when  the  RUN  command finishes executing, similar to a tmpfs
1291       mount point.
1292
1293
1294       Any subsequent execution of RUN commands sees the original  source  di‐
1295       rectory  content,  any changes from previous RUN commands no longer ex‐
1296       ists.
1297
1298
1299       One use case of the overlay mount is sharing the package cache from the
1300       host into the container to allow speeding up builds.
1301
1302
1303       Note:
1304
1305
1306               - Overlay mounts are not currently supported in rootless mode.
1307               - The `O` flag is not allowed to be specified with the `Z` or `z` flags.
1308
1309
1310
1311       Content mounted into the container is labeled with the private label.
1312              On  SELinux  systems, labels in the source directory needs to be
1313       readable by the container label. If not, SELinux  container  separation
1314       must be disabled for the container to work.
1315            -  Modification of the directory volume mounted into the container
1316       with an overlay mount can cause unexpected failures.  It is recommended
1317       that  you do not modify the directory until the container finishes run‐
1318       ning.
1319
1320
1321       By default bind mounted volumes are private. That means any mounts done
1322       inside  containers will not be visible on the host and vice versa. This
1323       behavior can be changed by specifying a volume mount propagation  prop‐
1324       erty.
1325
1326
1327       When  the  mount  propagation  policy is set to shared, any mounts com‐
1328       pleted inside the container on that volume will be visible to both  the
1329       host  and container. When the mount propagation policy is set to slave,
1330       one way mount propagation is enabled and any mounts  completed  on  the
1331       host  for  that volume will be visible only inside of the container. To
1332       control the mount propagation property of volume  use  the  :[r]shared,
1333       :[r]slave  or  :[r]private  propagation  flag. For mount propagation to
1334       work on the source mount point (mount point where source dir is mounted
1335       on)  has to have the right propagation properties.  For shared volumes,
1336       the source mount point has to be shared. And  for  slave  volumes,  the
1337       source mount has to be either shared or slave. [1] ⟨#Footnote1⟩
1338
1339
1340       Use  df <source-dir> to determine the source mount and then use findmnt
1341       -o TARGET,PROPAGATION <source-mount-dir> to determine propagation prop‐
1342       erties of source mount, if findmnt utility is not available, the source
1343       mount point can  be  determined  by  looking  at  the  mount  entry  in
1344       /proc/self/mountinfo.  Look  at optional fields and see if any propaga‐
1345       tion properties are specified.  shared:X means  the  mount  is  shared,
1346       master:X  means  the  mount is slave and if nothing is there that means
1347       the mount is private. [1] ⟨#Footnote1⟩
1348
1349
1350       To change propagation properties of a mount point use  the  mount  com‐
1351       mand.  For  example,  to  bind mount the source directory /foo do mount
1352       --bind /foo /foo and mount --make-private --make-shared /foo. This will
1353       convert  /foo into a shared mount point.  The propagation properties of
1354       the source mount can be changed directly. For  instance  if  /  is  the
1355       source mount for /foo, then use mount --make-shared / to convert / into
1356       a shared mount.
1357
1358

EXAMPLES

1360   Build an image using local Containerfiles
1361              $ podman build .
1362
1363              $ podman build -f Containerfile.simple .
1364
1365              $ cat $HOME/Containerfile | podman build -f - .
1366
1367              $ podman build -f Containerfile.simple -f Containerfile.notsosimple .
1368
1369              $ podman build -f Containerfile.in $HOME
1370
1371              $ podman build -t imageName .
1372
1373              $ podman build --tls-verify=true -t imageName -f Containerfile.simple .
1374
1375              $ podman build --tls-verify=false -t imageName .
1376
1377              $ podman build --runtime-flag log-format=json .
1378
1379              $ podman build --runtime-flag debug .
1380
1381              $ podman build --authfile /tmp/auths/myauths.json --cert-dir $HOME/auth --tls-verify=true --creds=username:password -t imageName -f Containerfile.simple .
1382
1383              $ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName .
1384
1385              $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName .
1386
1387              $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
1388
1389              $ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
1390
1391              $ podman build --layers -t imageName .
1392
1393              $ podman build --no-cache -t imageName .
1394
1395              $ podman build --layers --force-rm -t imageName .
1396
1397              $ podman build --no-cache --rm=false -t imageName .
1398
1399              $ podman build --network mynet .
1400
1401
1402
1403   Building a multi-architecture image using the --manifest  option  (requires
1404       emulation software)
1405              $ podman build --arch arm --manifest myimage /tmp/mysrc
1406
1407              $ podman build --arch amd64 --manifest myimage /tmp/mysrc
1408
1409              $ podman build --arch s390x --manifest myimage /tmp/mysrc
1410
1411              $ podman build --platform linux/s390x,linux/ppc64le,linux/amd64 --manifest myimage /tmp/mysrc
1412
1413              $ podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrc
1414
1415
1416
1417   Building an image using a URL, Git repo, or archive
1418       The  build  context directory can be specified as a URL to a Container‐
1419       file, a Git repository, or URL to an archive. If the URL is a  Contain‐
1420       erfile,  it  is downloaded to a temporary location and used as the con‐
1421       text. When a Git repository is set as the URL, the repository is cloned
1422       locally  to  a temporary location and then used as the context. Lastly,
1423       if the URL is an archive, it is downloaded to a temporary location  and
1424       extracted before being used as the context.
1425
1426
1427   Building an image using a URL to a Containerfile
1428       Podman will download the Containerfile to a temporary location and then
1429       use it as the build context.
1430
1431
1432              $ podman build https://10.10.10.1/podman/Containerfile
1433
1434
1435
1436   Building an image using a Git repository
1437       Podman will clone the specified GitHub repository to a temporary  loca‐
1438       tion  and  use  it as the context. The Containerfile at the root of the
1439       repository will be used and it only works if the GitHub repository is a
1440       dedicated repository.
1441
1442
1443              $ podman build https://github.com/scollier/purpletest
1444
1445
1446
1447       Note:  Github does not support using git:// for performing clone opera‐
1448       tion   due   to   recent   changes   in   their    security    guidance
1449       (https://github.blog/2021-09-01-improving-git-protocol-security-
1450       github/). Use an https:// URL if the source  repository  is  hosted  on
1451       Github.
1452
1453
1454   Building an image using a URL to an archive
1455       Podman will fetch the archive file, decompress it, and use its contents
1456       as the build context. The Containerfile at the root of the archive  and
1457       the  rest  of the archive will get used as the context of the build. If
1458       you pass -f PATH/Containerfile option as well, the system will look for
1459       that file inside the contents of the archive.
1460
1461
1462              $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz
1463
1464
1465
1466       Note:  supported  compression  formats  are  'xz',  'bzip2', 'gzip' and
1467       'identity' (no compression).
1468
1469

Files

1471   .containerignore/.dockerignore
1472       If the file .containerignore or .dockerignore exists in the context di‐
1473       rectory,  podman  build reads its contents. Use the --ignorefile option
1474       to override the Podman uses the content to exclude files  and  directo‐
1475       ries from the context directory, when executing COPY and ADD directives
1476       in the Containerfile/Dockerfile
1477
1478
1479       The .containerignore and .dockerignore files use the  same  syntax;  if
1480       both  are  in  the  context directory, podman build will only use .con‐
1481       tainerignore.
1482
1483
1484       Users can specify a series of Unix shell globs  in  a  .containerignore
1485       file to identify files/directories to exclude.
1486
1487
1488       Podman  supports  a special wildcard string ** which matches any number
1489       of directories (including zero). For example, */.go  will  exclude  all
1490       files that end with .go that are found in all directories.
1491
1492
1493       Example .containerignore file:
1494
1495
1496              # exclude this content for image
1497              */*.c
1498              **/output*
1499              src
1500
1501
1502
1503       */*.c  Excludes  files  and directories whose names ends with .c in any
1504       top level subdirectory. For  example,  the  source  file  include/root‐
1505       less.c.
1506
1507
1508       **/output* Excludes files and directories starting with output from any
1509       directory.
1510
1511
1512       src Excludes files named src and the directory src as well as any  con‐
1513       tent in it.
1514
1515
1516       Lines starting with ! (exclamation mark) can be used to make exceptions
1517       to exclusions. The following is an example .containerignore  file  that
1518       uses this mechanism:
1519
1520
1521              *.doc
1522              !Help.doc
1523
1524
1525
1526       Exclude all doc files except Help.doc from the image.
1527
1528
1529       This  functionality is compatible with the handling of .containerignore
1530       files described here:
1531
1532
1533       https://github.com/containers/common/blob/main/docs/containerig
1534       nore.5.md
1535
1536
1537       registries.conf (/etc/containers/registries.conf)
1538
1539
1540       registries.conf  is  the  configuration file which specifies which con‐
1541       tainer registries should be consulted when completing image names which
1542       do not include a registry or domain portion.
1543
1544

Troubleshooting

1546   lastlog sparse file
1547       If  you are using a useradd command within a Containerfile with a large
1548       UID/GID, it will create a large sparse file /var/log/lastlog.  This can
1549       cause  the  build to hang forever.  Go language does not support sparse
1550       files correctly, which can lead to some huge  files  being  created  in
1551       your container image.
1552
1553
1554       If  you are using useradd within your build script, you should pass the
1555       --no-log-init or -l option to the useradd command.  This  option  tells
1556       useradd to stop creating the lastlog file.
1557
1558

SEE ALSO

1560       podman(1),     buildah(1),    containers-certs.d(5),    containers-reg‐
1561       istries.conf(5), crun(1), runc(8),  useradd(8),  podman-ps(1),  podman-
1562       rm(1), Containerfile(5), containerignore(5)
1563
1564

HISTORY

1566       Aug  2020,  Additional  options and .containerignore added by Dan Walsh
1567       <dwalsh@redhat.com>
1568
1569
1570       May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com>
1571
1572
1573       December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com>
1574
1575

FOOTNOTES

1577       1: The Podman project is committed to inclusivity, a core value of open
1578       source. The master and slave mount propagation terminology used here is
1579       problematic and divisive, and should be changed.  However, these  terms
1580       are  currently  used  within the Linux kernel and must be used as-is at
1581       this time. When the kernel maintainers rectify this usage, Podman  will
1582       follow suit immediately.
1583
1584
1585
1586                                                               podman-build(1)
Impressum