1podman-create(1) General Commands Manual podman-create(1)
2
6 podman-create - Create a new container
7
10 podman create [options] image [command [arg ...]]
11 podman container create [options] image [command [arg ...]]
14
17 Creates a writable container layer over the specified image and pre‐
18 pares it for running the specified command. The container ID is then
19 printed to STDOUT. This is similar to podman run -d except the con‐
20 tainer is never started. Use the podman start container command to
21 start the container at any point.
22 The initial status of the container created with podman create is 'cre‐
25 ated'.
26 Default settings for flags are defined in containers.conf. Most set‐
29 tings for remote connections use the server's containers.conf, except
30 when documented in man pages.
31
34 The image is specified using transport:path format. If no transport is
35 specified, the docker (container registry) transport is used by de‐
36 fault. For remote Podman, including Mac and Windows (excluding WSL2)
37 machines, docker is the only allowed transport.
38 dir:path
41 An existing local directory path storing the manifest, layer tarballs
42 and signatures as individual files. This is a non-standardized format,
43 primarily useful for debugging or noninvasive container inspection.
44 $ podman save --format docker-dir fedora -o /tmp/fedora
47 $ podman create dir:/tmp/fedora echo hello
48 docker://docker-reference (Default)
52 An image reference stored in a remote container image registry. Ex‐
53 ample: "quay.io/podman/stable:latest". The reference can include a
54 path to a specific registry; if it does not, the registries listed in
55 registries.conf is queried to find a matching image. By default, cre‐
56 dentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
57 ers/auth.json by default) is used to authenticate; otherwise it falls
58 back to using credentials in $HOME/.docker/config.json.
59 $ podman create registry.fedoraproject.org/fedora:latest echo hello
62 docker-archive:path[:docker-reference] An image stored in the docker
66 save formatted file. docker-reference is only used when creating such a
67 file, and it must not contain a digest.
68 $ podman save --format docker-archive fedora -o /tmp/fedora
71 $ podman create docker-archive:/tmp/fedora echo hello
72 docker-daemon:docker-reference
76 An image in docker-reference format stored in the docker daemon in‐
77 ternal storage. The docker-reference can also be an image ID (docker-
78 daemon:algo:digest).
79 $ sudo docker pull fedora
82 $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83 oci-archive:path:tag
87 An image in a directory compliant with the "Open Container Image Lay‐
88 out Specification" at the specified path and specified with a tag.
89 $ podman save --format oci-archive fedora -o /tmp/fedora
92 $ podman create oci-archive:/tmp/fedora echo hello
93
97 --add-host=host:ip
98 Add a custom host-to-IP mapping (host:ip)
99 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102 tion can be set multiple times. Conflicts with the --no-hosts option.
103 --annotation=key=value
106 Add an annotation to the container. This option can be set multiple
107 times.
108 --arch=ARCH
111 Override the architecture, defaults to hosts, of the image to be
112 pulled. For example, arm. Unless overridden, subsequent lookups of the
113 same image in the local storage matches this architecture, regardless
114 of the host.
115 --attach, -a=stdin | stdout | stderr
118 Attach to STDIN, STDOUT or STDERR.
119 In foreground mode (the default when -d is not specified), podman run
122 can start the process in the container and attach the console to the
123 process's standard input, output, and error. It can even pretend to be
124 a TTY (this is what most command-line executables expect) and pass
125 along signals. The -a option can be set for each of stdin, stdout, and
126 stderr.
127 --authfile=path
130 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
131 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
132 dows/macOS. The file is created by podman login. If the authorization
133 state is not found there, $HOME/.docker/config.json is checked, which
134 is set using docker login.
135 Note: There is also the option to override the default path of the au‐
138 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
139 able. This can be done with export REGISTRY_AUTH_FILE=path.
140 --blkio-weight=weight
143 Block IO relative weight. The weight is a value between 10 and 1000.
144 This option is not supported on cgroups V1 rootless systems.
147 --blkio-weight-device=device:weight
150 Block IO relative device weight.
151 --cap-add=capability
154 Add Linux capabilities.
155 --cap-drop=capability
158 Drop Linux capabilities.
159 --cgroup-conf=KEY=VALUE
162 When running on cgroup v2, specify the cgroup file to write to and its
163 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
164 ory.high limit to 1GB.
165 --cgroup-parent=path
168 Path to cgroups under which the cgroup for the container is created. If
169 the path is not absolute, the path is considered to be relative to the
170 cgroups path of the init process. Cgroups are created if they do not
171 already exist.
172 --cgroupns=mode
175 Set the cgroup namespace mode for the container.
176 • host: use the host's cgroup namespace inside the container.
179 • container:id: join the namespace of the specified container.
181 • private: create a new cgroup namespace.
183 • ns:path: join the namespace at the specified path.
185 If the host uses cgroups v1, the default is set to host. On cgroups v2,
189 the default is private.
190 --cgroups=how
193 Determines whether the container creates CGroups.
194 Default is enabled.
197 The enabled option creates a new cgroup under the cgroup-parent. The
200 disabled option forces the container to not create CGroups, and thus
201 conflicts with CGroup options (--cgroupns and --cgroup-parent). The
202 no-conmon option disables a new CGroup only for the conmon process.
203 The split option splits the current CGroup in two sub-cgroups: one for
204 conmon and one for the container payload. It is not possible to set
205 --cgroup-parent with split.
206 --chrootdirs=path
209 Path to a directory inside the container that is treated as a chroot
210 directory. Any Podman managed file (e.g., /etc/resolv.conf,
211 /etc/hosts, etc/hostname) that is mounted into the root directory is
212 mounted into that location as well. Multiple directories are separated
213 with a comma.
214 --cidfile=file
217 Write the container ID to file. The file is removed along with the
218 container, except when used with podman --remote run on detached con‐
219 tainers.
220 --conmon-pidfile=file
223 Write the pid of the conmon process to a file. As conmon runs in a sep‐
224 arate process than Podman, this is necessary when using systemd to
225 restart Podman containers. (This option is not available with the re‐
226 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
227 chines)
228 --cpu-period=limit
231 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
232 duration in microseconds. Once the container's CPU quota is used up, it
233 will not be scheduled to run until the current period ends. Defaults to
234 100000 microseconds.
235 On some systems, changing the resource limits may not be allowed for
238 non-root users. For more details, see https://github.com/contain‐
239 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
240 source-limits-fails-with-a-permissions-error
241 This option is not supported on cgroups V1 rootless systems.
244 --cpu-quota=limit
247 Limit the CPU Completely Fair Scheduler (CFS) quota.
248 Limit the container's CPU usage. By default, containers run with the
251 full CPU resource. The limit is a number in microseconds. If a number
252 is provided, the container is allowed to use that much CPU time until
253 the CPU period ends (controllable via --cpu-period).
254 On some systems, changing the resource limits may not be allowed for
257 non-root users. For more details, see https://github.com/contain‐
258 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
259 source-limits-fails-with-a-permissions-error
260 This option is not supported on cgroups V1 rootless systems.
263 --cpu-rt-period=microseconds
266 Limit the CPU real-time period in microseconds.
267 Limit the container's Real Time CPU usage. This option tells the kernel
270 to restrict the container's Real Time CPU usage to the period speci‐
271 fied.
272 This option is only supported on cgroups V1 rootful systems.
275 --cpu-rt-runtime=microseconds
278 Limit the CPU real-time runtime in microseconds.
279 Limit the containers Real Time CPU usage. This option tells the kernel
282 to limit the amount of time in a given CPU period Real Time tasks may
283 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
284 this container can consume 95% of available CPU and leave the remaining
285 5% to normal priority tasks.
286 The sum of all runtimes across containers cannot exceed the amount al‐
289 lotted to the parent cgroup.
290 This option is only supported on cgroups V1 rootful systems.
293 --cpu-shares, -c=shares
296 CPU shares (relative weight).
297 By default, all containers get the same proportion of CPU cycles. This
300 proportion can be modified by changing the container's CPU share
301 weighting relative to the combined weight of all the running contain‐
302 ers. Default weight is 1024.
303 The proportion only applies when CPU-intensive processes are running.
306 When tasks in one container are idle, other containers can use the
307 left-over CPU time. The actual amount of CPU time varies depending on
308 the number of containers running on the system.
309 For example, consider three containers, one has a cpu-share of 1024 and
312 two others have a cpu-share setting of 512. When processes in all three
313 containers attempt to use 100% of CPU, the first container receives 50%
314 of the total CPU time. If a fourth container is added with a cpu-share
315 of 1024, the first container only gets 33% of the CPU. The remaining
316 containers receive 16.5%, 16.5% and 33% of the CPU.
317 On a multi-core system, the shares of CPU time are distributed over all
320 CPU cores. Even if a container is limited to less than 100% of CPU
321 time, it can use 100% of each individual CPU core.
322 For example, consider a system with more than three cores. If the con‐
325 tainer C0 is started with --cpu-shares=512 running one process, and an‐
326 other container C1 with --cpu-shares=1024 running two processes, this
327 can result in the following division of CPU shares:
328 ┌────┬───────────┬─────┬──────────────┐
331 │PID │ container │ CPU │ CPU share │
332 ├────┼───────────┼─────┼──────────────┤
333 │100 │ C0 │ 0 │ 100% of CPU0 │
334 ├────┼───────────┼─────┼──────────────┤
335 │101 │ C1 │ 1 │ 100% of CPU1 │
336 ├────┼───────────┼─────┼──────────────┤
337 │102 │ C1 │ 2 │ 100% of CPU2 │
338 └────┴───────────┴─────┴──────────────┘
339 On some systems, changing the resource limits may not be allowed for
341 non-root users. For more details, see https://github.com/contain‐
342 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
343 source-limits-fails-with-a-permissions-error
344 This option is not supported on cgroups V1 rootless systems.
347 --cpus=number
350 Number of CPUs. The default is 0.0 which means no limit. This is short‐
351 hand for --cpu-period and --cpu-quota, therefore the option cannot be
352 specified with --cpu-period or --cpu-quota.
353 On some systems, changing the CPU limits may not be allowed for non-
356 root users. For more details, see https://github.com/containers/pod‐
357 man/blob/main/troubleshooting.md#26-running-containers-with-resource-
358 limits-fails-with-a-permissions-error
359 This option is not supported on cgroups V1 rootless systems.
362 --cpuset-cpus=number
365 CPUs in which to allow execution. Can be specified as a comma-separated
366 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
367 (e.g. 0-3,7,11-15).
368 On some systems, changing the resource limits may not be allowed for
371 non-root users. For more details, see https://github.com/contain‐
372 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
373 source-limits-fails-with-a-permissions-error
374 This option is not supported on cgroups V1 rootless systems.
377 --cpuset-mems=nodes
380 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
381 tive on NUMA systems.
382 If there are four memory nodes on the system (0-3), use --cpuset-
385 mems=0,1 then processes in the container only uses memory from the
386 first two memory nodes.
387 On some systems, changing the resource limits may not be allowed for
390 non-root users. For more details, see https://github.com/contain‐
391 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
392 source-limits-fails-with-a-permissions-error
393 This option is not supported on cgroups V1 rootless systems.
396 --decryption-key=key[:passphrase]
399 The [key[:passphrase]] to be used for decryption of images. Key can
400 point to keys and/or certificates. Decryption is tried with all keys.
401 If the key is protected by a passphrase, it is required to be passed in
402 the argument and omitted otherwise.
403 --device=host-device[:container-device][:permissions]
406 Add a host device to the container. Optional permissions parameter can
407 be used to specify device permissions by combining r for read, w for
408 write, and m for mknod(2).
409 Example: --device=/dev/sdc:/dev/xvdc:rwm.
412 Note: if host-device is a symbolic link then it is resolved first. The
415 container only stores the major and minor numbers of the host device.
416 Podman may load kernel modules required for using the specified device.
419 The devices that Podman loads modules for when necessary are:
420 /dev/fuse.
421 In rootless mode, the new device is bind mounted in the container from
424 the host rather than Podman creating it within the container space. Be‐
425 cause the bind mount retains its SELinux label on SELinux systems, the
426 container can get permission denied when accessing the mounted device.
427 Modify SELinux settings to allow containers to use all device labels
428 via the following command:
429 $ sudo setsebool -P container_use_devices=true
432 Note: if the user only has access rights via a group, accessing the de‐
435 vice from inside a rootless container fails. Use the --group-add keep-
436 groups flag to pass the user's supplementary group access into the con‐
437 tainer.
438 --device-cgroup-rule="type major:minor mode"
441 Add a rule to the cgroup allowed devices list. The rule is expected to
442 be in the format specified in the Linux kernel documentation (Documen‐
443 tation/cgroup-v1/devices.txt):
444 - type: a (all), c (char), or b (block);
445 - major and minor: either a number, or * for all;
446 - mode: a composition of r (read), w (write), and m (mknod(2)).
447 --device-read-bps=path:rate
450 Limit read rate (in bytes per second) from a device (e.g. --device-
451 read-bps=/dev/sda:1mb).
452 On some systems, changing the resource limits may not be allowed for
455 non-root users. For more details, see https://github.com/contain‐
456 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
457 source-limits-fails-with-a-permissions-error
458 This option is not supported on cgroups V1 rootless systems.
461 --device-read-iops=path:rate
464 Limit read rate (in IO operations per second) from a device (e.g. --de‐
465 vice-read-iops=/dev/sda:1000).
466 On some systems, changing the resource limits may not be allowed for
469 non-root users. For more details, see https://github.com/contain‐
470 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
471 source-limits-fails-with-a-permissions-error
472 This option is not supported on cgroups V1 rootless systems.
475 --device-write-bps=path:rate
478 Limit write rate (in bytes per second) to a device (e.g. --device-
479 write-bps=/dev/sda:1mb).
480 On some systems, changing the resource limits may not be allowed for
483 non-root users. For more details, see https://github.com/contain‐
484 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
485 source-limits-fails-with-a-permissions-error
486 This option is not supported on cgroups V1 rootless systems.
489 --device-write-iops=path:rate
492 Limit write rate (in IO operations per second) to a device (e.g. --de‐
493 vice-write-iops=/dev/sda:1000).
494 On some systems, changing the resource limits may not be allowed for
497 non-root users. For more details, see https://github.com/contain‐
498 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
499 source-limits-fails-with-a-permissions-error
500 This option is not supported on cgroups V1 rootless systems.
503 --disable-content-trust
506 This is a Docker-specific option to disable image verification to a
507 container registry and is not supported by Podman. This option is a
508 NOOP and provided solely for scripting compatibility.
509 --dns=ipaddr
512 Set custom DNS servers.
513 This option can be used to override the DNS configuration passed to the
516 container. Typically this is necessary when the host DNS configuration
517 is invalid for the container (e.g., 127.0.0.1). When this is the case
518 the --dns flag is necessary for every run.
519 The special value none can be specified to disable creation of /etc/re‐
522 solv.conf in the container by Podman. The /etc/resolv.conf file in the
523 image is used without changes.
524 This option cannot be combined with --network that is set to none or
527 container:id.
528 --dns-option=option
531 Set custom DNS options. Invalid if using --dns-option with --network
532 that is set to none or container:id.
533 --dns-search=domain
536 Set custom DNS search domains. Invalid if using --dns-search with
537 --network that is set to none or container:id. Use --dns-search=. to
538 remove the search domain.
539 --entrypoint="command" | '["command", arg1 , ...]'
542 Override the default ENTRYPOINT from the image.
543 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
546 what executable to run when the container starts, but it is (purposely)
547 more difficult to override. The ENTRYPOINT gives a container its de‐
548 fault nature or behavior. When the ENTRYPOINT is set, the container
549 runs as if it were that binary, complete with default options. More op‐
550 tions can be passed in via the COMMAND. But, if a user wants to run
551 something else inside the container, the --entrypoint option allows a
552 new ENTRYPOINT to be specified.
553 Specify multi option commands in the form of a json string.
556 --env, -e=env
559 Set environment variables.
560 This option allows arbitrary environment variables that are available
563 for the process to be launched inside of the container. If an environ‐
564 ment variable is specified without a value, Podman checks the host en‐
565 vironment for a value and set the variable only if it is set on the
566 host. As a special case, if an environment variable ending in * is
567 specified without a value, Podman searches the host environment for
568 variables starting with the prefix and adds those variables to the con‐
569 tainer.
570 See Environment ⟨#environment⟩ note below for precedence and examples.
573 --env-file=file
576 Read in a line-delimited file of environment variables.
577 See Environment ⟨#environment⟩ note below for precedence and examples.
580 --env-host
583 Use host environment inside of the container. See Environment note be‐
584 low for precedence. (This option is not available with the remote Pod‐
585 man client, including Mac and Windows (excluding WSL2) machines)
586 --env-merge=env
589 Preprocess default environment variables for the containers. For exam‐
590 ple if image contains environment variable hello=world user can prepro‐
591 cess it using --env-merge hello=${hello}-some so new value is
592 hello=world-some.
593 Please note that if the environment variable hello is not present in
596 the image, then it'll be replaced by an empty string and so using
597 --env-merge hello=${hello}-some would result in the new value of
598 hello=-some, notice the leading - delimiter.
599 --expose=port
602 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
603 port redirection on the host system.
604 --gidmap=[flags]container_uid:from_uid[:amount]
607 Run the container in a new user namespace using the supplied GID map‐
608 ping. This option conflicts with the --userns and --subgidname options.
609 This option provides a way to map host GIDs to container GIDs in the
610 same way as --uidmap maps host UIDs to container UIDs. For details see
611 --uidmap.
612 Note: the --gidmap option cannot be called in conjunction with the
615 --pod option as a gidmap cannot be set on the container level when in a
616 pod.
617 --group-add=group | keep-groups
620 Assign additional groups to the primary user running within the con‐
621 tainer process.
622 • keep-groups is a special flag that tells Podman to keep the
625 supplementary group access.
626 Allows container to use the user's supplementary group access. If file
630 systems or devices are only accessible by the rootless user's group,
631 this flag tells the OCI runtime to pass the group access into the con‐
632 tainer. Currently only available with the crun OCI runtime. Note: keep-
633 groups is exclusive, other groups cannot be specified with this flag.
634 (Not available for remote commands, including Mac and Windows (exclud‐
635 ing WSL2) machines)
636 --group-entry=ENTRY
639 Customize the entry that is written to the /etc/group file within the
640 container when --user is used.
641 The variables $GROUPNAME, $GID, and $USERLIST are automatically re‐
644 placed with their value at runtime if present.
645 --health-cmd="command" | '["command", arg1 , ...]'
648 Set or alter a healthcheck command for a container. The command is a
649 command to be executed inside the container that determines the con‐
650 tainer health. The command is required for other healthcheck options to
651 be applied. A value of none disables existing healthchecks.
652 Multiple options can be passed in the form of a JSON array; otherwise,
655 the command is interpreted as an argument to /bin/sh -c.
656 --health-interval=interval
659 Set an interval for the healthchecks. An interval of disable results in
660 no automatic timer setup. The default is 30s.
661 --health-on-failure=action
664 Action to take once the container transitions to an unhealthy state.
665 The default is none.
666 • none: Take no action.
669 • kill: Kill the container.
671 • restart: Restart the container. Do not combine the restart
673 action with the --restart flag. When running inside of a sys‐
674 temd unit, consider using the kill or stop action instead to
675 make use of systemd's restart policy.
676 • stop: Stop the container.
678 --health-retries=retries
682 The number of retries allowed before a healthcheck is considered to be
683 unhealthy. The default value is 3.
684 --health-start-period=period
687 The initialization time needed for a container to bootstrap. The value
688 can be expressed in time format like 2m3s. The default value is 0s.
689 --health-startup-cmd="command" | '["command", arg1 , ...]'
692 Set a startup healthcheck command for a container. This command is exe‐
693 cuted inside the container and is used to gate the regular healthcheck.
694 When the startup command succeeds, the regular healthcheck begins and
695 the startup healthcheck ceases. Optionally, if the command fails for a
696 set number of attempts, the container is restarted. A startup
697 healthcheck can be used to ensure that containers with an extended
698 startup period are not marked as unhealthy until they are fully
699 started. Startup healthchecks can only be used when a regular
700 healthcheck (from the container's image or the --health-cmd option) is
701 also set.
702 --health-startup-interval=interval
705 Set an interval for the startup healthcheck. An interval of disable re‐
706 sults in no automatic timer setup. The default is 30s.
707 --health-startup-retries=retries
710 The number of attempts allowed before the startup healthcheck restarts
711 the container. If set to 0, the container is never restarted. The de‐
712 fault is 0.
713 --health-startup-success=retries
716 The number of successful runs required before the startup healthcheck
717 succeeds and the regular healthcheck begins. A value of 0 means that
718 any success begins the regular healthcheck. The default is 0.
719 --health-startup-timeout=timeout
722 The maximum time a startup healthcheck command has to complete before
723 it is marked as failed. The value can be expressed in a time format
724 like 2m3s. The default value is 30s.
725 --health-timeout=timeout
728 The maximum time allowed to complete the healthcheck before an interval
729 is considered failed. Like start-period, the value can be expressed in
730 a time format such as 1m22s. The default value is 30s.
731 --help
734 Print usage statement
735 --hostname, -h=name
738 Container host name
739 Sets the container host name that is available inside the container.
742 Can only be used with a private UTS namespace --uts=private (default).
743 If --pod is specified and the pod shares the UTS namespace (default)
744 the pod's hostname is used.
745 --hostuser=name
748 Add a user account to /etc/passwd from the host to the container. The
749 Username or UID must exist on the host system.
750 --http-proxy
753 By default proxy environment variables are passed into the container if
754 set for the Podman process. This can be disabled by setting the value
755 to false. The environment variables passed in include http_proxy,
756 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
757 those. This option is only needed when the host system must use a proxy
758 but the container does not use any proxy. Proxy environment variables
759 specified for the container in any other way overrides the values that
760 have been passed through from the host. (Other ways to specify the
761 proxy for the container include passing the values with the --env flag,
762 or hard coding the proxy environment at container build time.) When
763 used with the remote client it uses the proxy environment variables
764 that are set on the server process.
765 Defaults to true.
768 --image-volume=bind | tmpfs | ignore
771 Tells Podman how to handle the builtin image volumes. Default is bind.
772 • bind: An anonymous named volume is created and mounted into
775 the container.
776 • tmpfs: The volume is mounted onto the container as a tmpfs,
778 which allows the users to create content that disappears when
779 the container is stopped.
780 • ignore: All volumes are just ignored and no action is taken.
782 --init
786 Run an init inside the container that forwards signals and reaps pro‐
787 cesses. The container-init binary is mounted at /run/podman-init.
788 Mounting over /run breaks container execution.
789 --init-ctr=type
792 (Pods only). When using pods, create an init style container, which is
793 run after the infra container is started but before regular pod con‐
794 tainers are started. Init containers are useful for running setup op‐
795 erations for the pod's applications.
796 Valid values for init-ctr type are always or once. The always value
799 means the container runs with each and every pod start, whereas the
800 once value means the container only runs once when the pod is started
801 and then the container is removed.
802 Init containers are only run on pod start. Restarting a pod does not
805 execute any init containers. Furthermore, init containers can only be
806 created in a pod when that pod is not running.
807 --init-path=path
810 Path to the container-init binary.
811 --interactive, -i
814 When set to true, keep stdin open even if not attached. The default is
815 false.
816 --ip=ipv4
819 Specify a static IPv4 address for the container, for example
820 10.88.64.128. This option can only be used if the container is joined
821 to only a single network - i.e., --network=network-name is used at most
822 once - and if the container is not joining another container's network
823 namespace via --network=container:id. The address must be within the
824 network's IP address pool (default 10.88.0.0/16).
825 To specify multiple static IP addresses per container, set multiple
828 networks using the --network option with a static IP address specified
829 for each using the ip mode for that option.
830 --ip6=ipv6
833 Specify a static IPv6 address for the container, for example
834 fd46:db93:aa76:ac37::10. This option can only be used if the container
835 is joined to only a single network - i.e., --network=network-name is
836 used at most once - and if the container is not joining another con‐
837 tainer's network namespace via --network=container:id. The address
838 must be within the network's IPv6 address pool.
839 To specify multiple static IPv6 addresses per container, set multiple
842 networks using the --network option with a static IPv6 address speci‐
843 fied for each using the ip6 mode for that option.
844 --ipc=ipc
847 Set the IPC namespace mode for a container. The default is to create a
848 private IPC namespace.
849 • "": Use Podman's default, defined in containers.conf.
852 • container:id: reuses another container's shared memory, sema‐
854 phores, and message queues
855 • host: use the host's shared memory, semaphores, and message
857 queues inside the container. Note: the host mode gives the
858 container full access to local shared memory and is therefore
859 considered insecure.
860 • none: private IPC namespace, with /dev/shm not mounted.
862 • ns:path: path to an IPC namespace to join.
864 • private: private IPC namespace.
866 • shareable: private IPC namespace with a possibility to share
868 it with other containers.
869 --label, -l=key=value
873 Add metadata to a container.
874 --label-file=file
877 Read in a line-delimited file of labels.
878 --link-local-ip=ip
881 Not implemented.
882 --log-driver=driver
885 Logging driver for the container. Currently available options are k8s-
886 file, journald, none and passthrough, with json-file aliased to k8s-
887 file for scripting compatibility. (Default journald).
888 The podman info command below displays the default log-driver for the
891 system.
892 $ podman info --format '{{ .Host.LogDriver }}'
895 journald
896 The passthrough driver passes down the standard streams (stdin, stdout,
900 stderr) to the container. It is not allowed with the remote Podman
901 client, including Mac and Windows (excluding WSL2) machines, and on a
902 tty, since it is vulnerable to attacks via TIOCSTI.
903 --log-opt=name=value
906 Logging driver specific options.
907 Set custom logging configuration. The following *name*s are supported:
910 path: specify a path to the log file
913 (e.g. --log-opt path=/var/log/container/mycontainer.json);
914 max-size: specify a max size of the log file
917 (e.g. --log-opt max-size=10mb);
918 tag: specify a custom log tag for the container
921 (e.g. --log-opt tag="{{.ImageName}}". It supports the same keys as
922 podman inspect --format. This option is currently supported only by
923 the journald log driver.
924 --mac-address=address
927 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
928 option can only be used if the container is joined to only a single
929 network - i.e., --network=network-name is used at most once - and if
930 the container is not joining another container's network namespace via
931 --network=container:id.
932 Remember that the MAC address in an Ethernet network must be unique.
935 The IPv6 link-local address is based on the device's MAC address ac‐
936 cording to RFC4862.
937 To specify multiple static MAC addresses per container, set multiple
940 networks using the --network option with a static MAC address specified
941 for each using the mac mode for that option.
942 --memory, -m=number[unit]
945 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
946 g (gibibytes).
947 Allows the memory available to a container to be constrained. If the
950 host supports swap memory, then the -m memory setting can be larger
951 than physical RAM. If a limit of 0 is specified (not using -m), the
952 container's memory is not limited. The actual limit may be rounded up
953 to a multiple of the operating system's page size (the value is very
954 large, that's millions of trillions).
955 This option is not supported on cgroups V1 rootless systems.
958 --memory-reservation=number[unit]
961 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
962 (mebibytes), or g (gibibytes).
963 After setting memory reservation, when the system detects memory con‐
966 tention or low memory, containers are forced to restrict their consump‐
967 tion to their reservation. So always set the value below --memory, oth‐
968 erwise the hard limit takes precedence. By default, memory reservation
969 is the same as memory limit.
970 This option is not supported on cgroups V1 rootless systems.
973 --memory-swap=number[unit]
976 A limit value equal to memory plus swap. A unit can be b (bytes), k
977 (kibibytes), m (mebibytes), or g (gibibytes).
978 Must be used with the -m (--memory) flag. The argument value must be
981 larger than that of
982 -m (--memory) By default, it is set to double the value of --memory.
983 Set number to -1 to enable unlimited swap.
986 This option is not supported on cgroups V1 rootless systems.
989 --memory-swappiness=number
992 Tune a container's memory swappiness behavior. Accepts an integer be‐
993 tween 0 and 100.
994 This flag is only supported on cgroups V1 rootful systems.
997 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
1000 Attach a filesystem mount to the container
1001 Current supported mount TYPEs are bind, devpts, glob, image, ramfs,
1004 tmpfs and volume. [1] ⟨#Footnote1⟩
1005 e.g.
1008 type=bind,source=/path/on/host,destination=/path/in/container
1009 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
1011 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
1013 type=devpts,destination=/dev/pts
1015 type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true
1017 type=image,source=fedora,destination=/fedora-image,rw=true
1019 type=ramfs,tmpfs-size=512M,destination=/path/in/container
1021 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
1023 type=tmpfs,destination=/path/in/container,noswap
1025 type=volume,source=vol1,destination=/path/in/container,ro=true
1027 Common Options:
1029 · src, source: mount source spec for bind, glob, and volume. Mandatory for bind and glob.
1031 · dst, destination, target: mount destination spec.
1033 When source globs are specified without the destination directory,
1035 the files and directories are mounted with their complete path
1036 within the container. When the destination is specified, the
1037 files and directories matching the glob on the base file name
1038 on the destination directory are mounted. The option
1039 `type=glob,src=/foo*,destination=/tmp/bar` tells container engines
1040 to mount host files matching /foo* to the /tmp/bar/
1041 directory in the container.
1042 Options specific to volume:
1044 · ro, readonly: true or false (default).
1046 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1048 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1050 The idmap option supports a custom mapping that can be different than the user namespace used by the container.
1051 The mapping can be specified after the idmap option like: `idmap=uids=0-1-10#10-11-10;gids=0-100-10`. For each triplet, the first value is the
1052 start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value.
1053 Multiple ranges are separated with #. If the specified mapping is prepended with a '@' then the mapping is considered relative to the container
1054 user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace.
1055 Options specific to image:
1057 · rw, readwrite: true or false (default).
1059 Options specific to bind and glob:
1061 · ro, readonly: true or false (default).
1063 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
1065 . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
1067 . relabel: shared, private.
1069 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1071 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1073 Options specific to tmpfs and ramfs:
1075 · ro, readonly: true or false (default).
1077 · tmpfs-size: Size of the tmpfs/ramfs mount in bytes. Unlimited by default in Linux.
1079 · tmpfs-mode: File mode of the tmpfs/ramfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1081 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default.
1083 · notmpcopyup: Disable copying files from the image to the tmpfs/ramfs.
1085 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1087 Options specific to devpts:
1089 · uid: UID of the file owner (default 0).
1091 · gid: GID of the file owner (default 0).
1093 · mode: permission mask for the file (default 600).
1095 · max: maximum number of PTYs (default 1048576).
1097 --name=name
1101 Assign a name to the container.
1102 The operator can identify a container in three ways:
1105 • UUID long identifier
1108 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1109 • UUID short identifier (“f78375b1c487”);
1111 • Name (“jonah”).
1113 Podman generates a UUID for each container, and if a name is not as‐
1117 signed to the container with --name then it generates a random string
1118 name. The name can be useful as a more human-friendly way to identify
1119 containers. This works for both background and foreground containers.
1120 --network=mode, --net
1123 Set the network mode for the container.
1124 Valid mode values are:
1127 • bridge[:OPTIONS,...]: Create a network stack on the default
1130 bridge. This is the default for rootful containers. It is pos‐
1131 sible to specify these additional options:
1132 • alias=name: Add network-scoped alias for the container.
1134 • ip=IPv4: Specify a static ipv4 address for this container.
1136 • ip=IPv6: Specify a static ipv6 address for this container.
1138 • mac=MAC: Specify a static mac address for this container.
1140 • interface_name: Specify a name for the created network in‐
1142 terface inside the container.
1143 For example to set a static ipv4 address and a static mac ad‐
1145 dress, use --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.
1146 • <network name or ID>[:OPTIONS,...]: Connect to a user-defined
1148 network; this is the network name or ID from a network created
1149 by podman network create. Using the network name implies the
1150 bridge network mode. It is possible to specify the same op‐
1151 tions described under the bridge mode above. Use the --network
1152 option multiple times to specify additional networks. For
1153 backwards compatibility it is also possible to specify net‐
1154 works comma separated on the first --network argument, however
1155 this prevents you from using the options described under the
1156 bridge section above.
1157 • none: Create a network namespace for the container but do not
1159 configure network interfaces for it, thus the container has no
1160 network connectivity.
1161 • container:id: Reuse another container's network stack.
1163 • host: Do not create a network namespace, the container uses
1165 the host's network. Note: The host mode gives the container
1166 full access to local system services such as D-bus and is
1167 therefore considered insecure.
1168 • ns:path: Path to a network namespace to join.
1170 • private: Create a new namespace for the container. This uses
1172 the bridge mode for rootful containers and slirp4netns for
1173 rootless ones.
1174 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
1176 network stack. This is the default for rootless containers. It
1177 is possible to specify these additional options, they can also
1178 be set with network_cmd_options in containers.conf:
1179 • allow_host_loopback=true|false: Allow slirp4netns to reach
1181 the host loopback IP (default is 10.0.2.2 or the second IP
1182 from slirp4netns cidr subnet when changed, see the cidr op‐
1183 tion below). The default is false.
1184 • mtu=MTU: Specify the MTU to use for this network. (Default
1186 is 65520).
1187 • cidr=CIDR: Specify ip range to use for this network. (De‐
1189 fault is 10.0.2.0/24).
1190 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
1192 quired for outbound_addr6).
1193 • outbound_addr=INTERFACE: Specify the outbound interface
1195 slirp binds to (ipv4 traffic only).
1196 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
1198 binds to.
1199 • outbound_addr6=INTERFACE: Specify the outbound interface
1201 slirp binds to (ipv6 traffic only).
1202 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
1204 binds to.
1205 • port_handler=rootlesskit: Use rootlesskit for port forward‐
1207 ing. Default. Note: Rootlesskit changes the source IP ad‐
1208 dress of incoming packets to an IP address in the container
1209 network namespace, usually 10.0.2.100. If the application
1210 requires the real source IP address, e.g. web server logs,
1211 use the slirp4netns port handler. The rootlesskit port han‐
1212 dler is also used for rootless containers when connected to
1213 user-defined networks.
1214 • port_handler=slirp4netns: Use the slirp4netns port forward‐
1216 ing, it is slower than rootlesskit but preserves the correct
1217 source IP address. This port handler cannot be used for
1218 user-defined networks.
1219 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
1223 working stack.
1224 This is only supported in rootless mode.
1225 By default, IPv4 and IPv6 addresses and routes, as well as the
1226 pod interface name, are copied from the host. If port forward‐
1227 ing isn't configured, ports are forwarded dynamically as ser‐
1228 vices are bound on either side (init namespace or container
1229 namespace). Port forwarding preserves the original source IP
1230 address. Options described in pasta(1) can be specified as
1231 comma-separated arguments.
1232 In terms of pasta(1) options, --config-net is given by de‐
1233 fault, in order to configure networking when the container is
1234 started, and --no-map-gw is also assumed by default, to avoid
1235 direct access from container to host using the gateway ad‐
1236 dress. The latter can be overridden by passing --map-gw in the
1237 pasta-specific options (despite not being an actual pasta(1)
1238 option).
1239 Also, -t none and -u none are passed if, respectively, no TCP
1240 or UDP port forwarding from host to container is configured,
1241 to disable automatic port forwarding based on bound ports.
1242 Similarly, -T none and -U none are given to disable the same
1243 functionality from container to host.
1244 Some examples:
1245 • pasta:--map-gw: Allow the container to directly reach the
1247 host using the gateway address.
1248 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
1250 terface in the container.
1251 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
1253 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
1254 alent to default slirp4netns(1) options: disable IPv6, as‐
1255 sign 10.0.2.0/24 to the tap0 interface in the container,
1256 with gateway 10.0.2.3, enable DNS forwarder reachable at
1257 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
1258 DHCP support.
1259 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
1261 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
1262 to default slirp4netns(1) options with Podman overrides:
1263 same as above, but leave the MTU to 65520 bytes
1264 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
1266 forwarding based on observed bound ports from both host and
1267 container sides
1268 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
1270 tainer to host, using the loopback interface instead of the
1271 tap interface for improved performance
1272 NOTE: For backward compatibility reasons, if there is an exist‐
1274 ing network named pasta, Podman uses it instead of the pasta
1275 mode."?
1276 Invalid if using --dns, --dns-option, or --dns-search with --network
1280 set to none or container:id.
1281 If used together with --pod, the container does not join the pod's net‐
1284 work namespace.
1285 --network-alias=alias
1288 Add a network-scoped alias for the container, setting the alias for all
1289 networks that the container joins. To set a name only for a specific
1290 network, use the alias option as described under the --network option.
1291 If the network has DNS enabled (podman network inspect -f {{.DNSEn‐
1292 abled}} <name>), these aliases can be used for name resolution on the
1293 given network. This option can be specified multiple times. NOTE: When
1294 using CNI a container only has access to aliases on the first network
1295 that it joins. This limitation does not exist with netavark/aardvark-
1296 dns.
1297 --no-healthcheck
1300 Disable any defined healthchecks for container.
1301 --no-hosts
1304 Do not create /etc/hosts for the container. By default, Podman manages
1305 /etc/hosts, adding the container's own IP address and any hosts from
1306 --add-host. --no-hosts disables this, and the image's /etc/hosts is
1307 preserved unmodified.
1308 This option conflicts with --add-host.
1311 --oom-kill-disable
1314 Whether to disable OOM Killer for the container or not.
1315 This flag is not supported on cgroups V2 systems.
1318 --oom-score-adj=num
1321 Tune the host's OOM preferences for containers (accepts values from
1322 -1000 to 1000).
1323 When running in rootless mode, the specified value can't be lower than
1326 the oom_score_adj for the current process. In this case, the oom-score-
1327 adj is clamped to the current process value.
1328 --os=OS
1331 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1332 ample, windows. Unless overridden, subsequent lookups of the same im‐
1333 age in the local storage matches this OS, regardless of the host.
1334 --passwd-entry=ENTRY
1337 Customize the entry that is written to the /etc/passwd file within the
1338 container when --passwd is used.
1339 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1342 placed with their value at runtime.
1343 --personality=persona
1346 Personality sets the execution domain via Linux personality(2).
1347 --pid=mode
1350 Set the PID namespace mode for the container. The default is to create
1351 a private PID namespace for the container.
1352 • container:id: join another container's PID namespace;
1355 • host: use the host's PID namespace for the container. Note the
1357 host mode gives the container full access to local PID and is
1358 therefore considered insecure;
1359 • ns:path: join the specified PID namespace;
1361 • private: create a new namespace for the container (default).
1363 --pidfile=path
1367 When the pidfile location is specified, the container process' PID is
1368 written to the pidfile. (This option is not available with the remote
1369 Podman client, including Mac and Windows (excluding WSL2) machines) If
1370 the pidfile option is not specified, the container process' PID is
1371 written to /run/containers/storage/${storage-driver}-contain‐
1372 ers/$CID/userdata/pidfile.
1373 After the container is started, the location for the pidfile can be
1376 discovered with the following podman inspect command:
1377 $ podman inspect --format '{{ .PidFile }}' $CID
1380 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1381 --pids-limit=limit
1385 Tune the container's pids limit. Set to -1 to have unlimited pids for
1386 the container. The default is 2048 on systems that support "pids"
1387 cgroup controller.
1388 --platform=OS/ARCH
1391 Specify the platform for selecting the image. (Conflicts with --arch
1392 and --os) The --platform option can be used to override the current ar‐
1393 chitecture and operating system. Unless overridden, subsequent lookups
1394 of the same image in the local storage matches this platform, regard‐
1395 less of the host.
1396 --pod=name
1399 Run container in an existing pod. Podman makes the pod automatically if
1400 the pod name is prefixed with new:. To make a pod with more granular
1401 options, use the podman pod create command before creating a container.
1402 When a container is run with a pod with an infra-container, the infra-
1403 container is started first.
1404 --pod-id-file=file
1407 Run container in an existing pod and read the pod's ID from the speci‐
1408 fied file. When a container is run within a pod which has an infra-
1409 container, the infra-container starts first.
1410 --privileged
1413 Give extended privileges to this container. The default is false.
1414 By default, Podman containers are unprivileged (=false) and cannot, for
1417 example, modify parts of the operating system. This is because by de‐
1418 fault a container is only allowed limited access to devices. A "privi‐
1419 leged" container is given the same access to devices as the user
1420 launching the container, with the exception of virtual consoles
1421 (/dev/tty\d+) when running in systemd mode (--systemd=always).
1422 A privileged container turns off the security features that isolate the
1425 container from the host. Dropped Capabilities, limited devices, read-
1426 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1427 all disabled.
1428 Rootless containers cannot have more privileges than the account that
1431 launched them.
1432 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1435 Publish a container's port, or range of ports, to the host.
1436 Both hostPort and containerPort can be specified as a range of ports.
1439 When specifying ranges for both, the number of container ports in the
1440 range must match the number of host ports in the range.
1441 If host IP is set to 0.0.0.0 or not set at all, the port is bound on
1444 all IPs on the host.
1445 By default, Podman publishes TCP ports. To publish a UDP port instead,
1448 give udp as protocol. To publish both TCP and UDP ports, set --publish
1449 twice, with tcp, and udp as protocols respectively. Rootful containers
1450 can also publish ports using the sctp protocol.
1451 Host port does not have to be specified (e.g. podman run -p
1454 127.0.0.1::80). If it is not, the container port is randomly assigned
1455 a port on the host.
1456 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1459 TAINERPORT.
1460 Note: If a container runs within a pod, it is not necessary to publish
1463 the port for the containers in the pod. The port must only be published
1464 by the pod itself. Pod network stacks act like the network stack on the
1465 host - when there are a variety of containers in the pod, and programs
1466 in the container, all sharing a single interface and IP address, and
1467 associated ports. If one container binds to a port, no other container
1468 can use that port within the pod while it is in use. Containers in the
1469 pod can also communicate over localhost by having one container bind to
1470 localhost in the pod, and another connect to that port.
1471 --publish-all, -P
1474 Publish all exposed ports to random ports on the host interfaces. The
1475 default is false.
1476 When set to true, publish all exposed ports to the host interfaces. If
1479 the operator uses -P (or -p) then Podman makes the exposed port acces‐
1480 sible on the host and the ports are available to any client that can
1481 reach the host.
1482 When using this option, Podman binds any exposed port to a random port
1485 on the host within an ephemeral port range defined by
1486 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1487 the host ports and the exposed ports, use podman port.
1488 --pull=policy
1491 Pull image policy. The default is missing.
1492 • always: Always pull the image and throw an error if the pull
1495 fails.
1496 • missing: Pull the image only when the image is not in the lo‐
1498 cal containers storage. Throw an error if no image is found
1499 and the pull fails.
1500 • never: Never pull the image but use the one from the local
1502 containers storage. Throw an error if no image is found.
1503 • newer: Pull if the image on the registry is newer than the one
1505 in the local containers storage. An image is considered to be
1506 newer when the digests are different. Comparing the time
1507 stamps is prone to errors. Pull errors are suppressed if a
1508 local image was found.
1509 --quiet, -q
1513 Suppress output information when pulling images
1514 --read-only
1517 Mount the container's root filesystem as read-only.
1518 By default, container root filesystems are writable, allowing processes
1521 to write files anywhere. By specifying the --read-only flag, the con‐
1522 tainers root filesystem are mounted read-only prohibiting any writes.
1523 --read-only-tmpfs
1526 If container is running in --read-only mode, then mount a read-write
1527 tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp. The default is true.
1528 --replace
1531 If another container with the same name already exists, replace and re‐
1532 move it. The default is false.
1533 --requires=container
1536 Specify one or more requirements. A requirement is a dependency con‐
1537 tainer that is started before this container. Containers can be speci‐
1538 fied by name or ID, with multiple containers being separated by commas.
1539 --restart=policy
1542 Restart policy to follow when containers exit. Restart policy does not
1543 take effect if a container is stopped via the podman kill or podman
1544 stop commands.
1545 Valid policy values are:
1548 • no : Do not restart containers on exit
1551 • never : Synonym for no; do not restart con‐
1553 tainers on exit
1554 • on-failure[:max_retries] : Restart containers when they exit
1556 with a non-zero exit code, retrying indefinitely or until the
1557 optional max_retries count is hit
1558 • always : Restart containers when they exit,
1560 regardless of status, retrying indefinitely
1561 • unless-stopped : Identical to always
1563 Podman provides a systemd unit file, podman-restart.service, which
1567 restarts containers after a system reboot.
1568 When running containers in systemd services, use the restart function‐
1571 ality provided by systemd. In other words, do not use this option in a
1572 container unit, instead set the Restart= systemd directive in the [Ser‐
1573 vice] section. See podman-systemd.unit(5) and systemd.service(5).
1574 --rm
1577 Automatically remove the container and any anonymous unnamed volume as‐
1578 sociated with the container when it exits. The default is false.
1579 --rootfs
1582 If specified, the first argument refers to an exploded container on the
1583 file system.
1584 This is useful to run a container without requiring any image manage‐
1587 ment, the rootfs of the container is assumed to be managed externally.
1588 Overlay Rootfs Mounts
1591 The :O flag tells Podman to mount the directory from the rootfs path as
1594 storage using the overlay file system. The container processes can mod‐
1595 ify content within the mount point which is stored in the container
1596 storage in a separate directory. In overlay terms, the source directory
1597 is the lower, and the container storage directory is the upper. Modifi‐
1598 cations to the mount point are destroyed when the container finishes
1599 executing, similar to a tmpfs mount point being unmounted.
1600 Note: On SELinux systems, the rootfs needs the correct label, which is
1603 by default unconfined_u:object_r:container_file_t:s0.
1604 idmap
1607 If idmap is specified, create an idmapped mount to the target user
1610 namespace in the container. The idmap option supports a custom mapping
1611 that can be different than the user namespace used by the container.
1612 The mapping can be specified after the idmap option like:
1613 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
1614 value is the start of the backing file system IDs that are mapped to
1615 the second value on the host. The length of this mapping is given in
1616 the third value. Multiple ranges are separated with #.
1617 --sdnotify=container | conmon | healthy | ignore
1620 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1621 Type=notify.
1622 Default is container, which means allow the OCI runtime to proxy the
1625 socket into the container to receive ready notification. Podman sets
1626 the MAINPID to conmon's pid. The conmon option sets MAINPID to con‐
1627 mon's pid, and sends READY when the container has started. The socket
1628 is never passed to the runtime or the container. The healthy option
1629 sets MAINPID to conmon's pid, and sends READY when the container has
1630 turned healthy; requires a healthcheck to be set. The socket is never
1631 passed to the runtime or the container. The ignore option removes NO‐
1632 TIFY_SOCKET from the environment for itself and child processes, for
1633 the case where some other process above Podman uses NOTIFY_SOCKET and
1634 Podman does not use it.
1635 --seccomp-policy=policy
1638 Specify the policy to select the seccomp profile. If set to image, Pod‐
1639 man looks for a "io.containers.seccomp.profile" label in the container-
1640 image config and use its value as a seccomp profile. Otherwise, Podman
1641 follows the default policy by applying the default profile unless spec‐
1642 ified otherwise via --security-opt seccomp as described below.
1643 Note that this feature is experimental and may change in the future.
1646 --secret=secret[,opt=opt ...]
1649 Give the container access to a secret. Can be specified multiple times.
1650 A secret is a blob of sensitive data which a container needs at runtime
1653 but is not stored in the image or in source control, such as usernames
1654 and passwords, TLS certificates and keys, SSH keys or other important
1655 generic strings or binary content (up to 500 kb in size).
1656 When secrets are specified as type mount, the secrets are copied and
1659 mounted into the container when a container is created. When secrets
1660 are specified as type env, the secret is set as an environment variable
1661 within the container. Secrets are written in the container at the time
1662 of container creation, and modifying the secret using podman secret
1663 commands after the container is created affects the secret inside the
1664 container.
1665 Secrets and its storage are managed using the podman secret command.
1668 Secret Options
1671 • type=mount|env : How the secret is exposed to the con‐
1674 tainer.
1675 mount mounts the secret into the container
1676 as a file.
1677 env exposes the secret as an environment
1678 variable.
1679 Defaults to mount.
1680 • target=target : Target of secret.
1682 For mounted secrets, this is the path to
1683 the secret inside the container.
1684 If a fully qualified path is provided, the
1685 secret is mounted at that location.
1686 Otherwise, the secret is mounted to
1687 /run/secrets/target for linux containers
1688 or
1689 /var/run/secrets/target for freebsd con‐
1690 tainers.
1691 If the target is not set, the secret is
1692 mounted to /run/secrets/secretname by default.
1693 For env secrets, this is the environment
1694 variable key. Defaults to secretname.
1695 • uid=0 : UID of secret. Defaults to 0. Mount secret
1697 type only.
1698 • gid=0 : GID of secret. Defaults to 0. Mount secret
1700 type only.
1701 • mode=0 : Mode of secret. Defaults to 0444. Mount
1703 secret type only.
1704 Examples
1708 Mount at /my/location/mysecret with UID 1:
1711 --secret mysecret,target=/my/location/mysecret,uid=1
1714 Mount at /run/secrets/customtarget with mode 0777:
1718 --secret mysecret,target=customtarget,mode=0777
1721 Create a secret environment variable called ENVSEC:
1725 --secret mysecret,type=env,target=ENVSEC
1728 --security-opt=option
1732 Security Options
1733 • apparmor=unconfined : Turn off apparmor confinement for the
1736 container
1737 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1739 file for the container
1740 • label=user:USER: Set the label user for the container pro‐
1742 cesses
1743 • label=role:ROLE: Set the label role for the container pro‐
1745 cesses
1746 • label=type:TYPE: Set the label process type for the container
1748 processes
1749 • label=level:LEVEL: Set the label level for the container pro‐
1751 cesses
1752 • label=filetype:TYPE: Set the label file type for the container
1754 files
1755 • label=disable: Turn off label separation for the container
1757 Note: Labeling can be disabled for all containers by setting la‐
1761 bel=false in the containers.conf (/etc/containers/containers.conf or
1762 $HOME/.config/containers/containers.conf) file.
1763 • label=nested: Allows SELinux modifications within the con‐
1766 tainer. Containers are allowed to modify SELinux labels on
1767 files and processes, as long as SELinux policy allows. Without
1768 nested, containers view SELinux as disabled, even when it is
1769 enabled on the host. Containers are prevented from setting any
1770 labels.
1771 • mask=/path/1:/path/2: The paths to mask separated by a colon.
1773 A masked path cannot be accessed inside the container.
1774 • no-new-privileges: Disable container processes from gaining
1776 additional privileges.
1777 • seccomp=unconfined: Turn off seccomp confinement for the con‐
1779 tainer.
1780 • seccomp=profile.json: JSON file to be used as a seccomp fil‐
1782 ter. Note that the io.podman.annotations.seccomp annotation is
1783 set with the specified value as shown in podman inspect.
1784 • proc-opts=OPTIONS : Comma-separated list of options to use for
1786 the /proc mount. More details for the possible mount options
1787 are specified in the proc(5) man page.
1788 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1790 (/proc/*): Paths to unmask separated by a colon. If set to
1791 ALL, it unmasks all the paths that are masked or made read-
1792 only by default. The default masked paths are /proc/acpi,
1793 /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_de‐
1794 bug, /proc/scsi, /proc/timer_list, /proc/timer_stats,
1795 /sys/firmware, and /sys/fs/selinux. The default paths that
1796 are read-only are /proc/asound, /proc/bus, /proc/fs,
1797 /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1798 Note: Labeling can be disabled for all containers by setting la‐
1802 bel=false in the containers.conf(5) file.
1803 --shm-size=number[unit]
1806 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1807 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1808 bytes. If the size is omitted, the default is 64m. When size is 0,
1809 there is no limit on the amount of memory used for IPC by the con‐
1810 tainer. This option conflicts with --ipc=host.
1811 --shm-size-systemd=number[unit]
1814 Size of systemd-specific tmpfs mounts such as /run, /run/lock,
1815 /var/log/journal and /tmp. A unit can be b (bytes), k (kibibytes), m
1816 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1817 bytes. If the size is omitted, the default is 64m. When size is 0, the
1818 usage is limited to 50% of the host's available memory.
1819 --stop-signal=signal
1822 Signal to stop a container. Default is SIGTERM.
1823 --stop-timeout=seconds
1826 Timeout to stop a container. Default is 10. Remote connections use lo‐
1827 cal containers.conf for defaults.
1828 --subgidname=name
1831 Run the container in a new user namespace using the map with name in
1832 the /etc/subgid file. If running rootless, the user needs to have the
1833 right to use the mapping. See subgid(5). This flag conflicts with
1834 --userns and --gidmap.
1835 --subuidname=name
1838 Run the container in a new user namespace using the map with name in
1839 the /etc/subuid file. If running rootless, the user needs to have the
1840 right to use the mapping. See subuid(5). This flag conflicts with
1841 --userns and --uidmap.
1842 --sysctl=name=value
1845 Configure namespaced kernel parameters at runtime.
1846 For the IPC namespace, the following sysctls are allowed:
1849 • kernel.msgmax
1852 • kernel.msgmnb
1854 • kernel.msgmni
1856 • kernel.sem
1858 • kernel.shmall
1860 • kernel.shmmax
1862 • kernel.shmmni
1864 • kernel.shm_rmid_forced
1866 • Sysctls beginning with fs.mqueue.*
1868 Note: if using the --ipc=host option, the above sysctls are not al‐
1872 lowed.
1873 For the network namespace, only sysctls beginning with net.* are al‐
1876 lowed.
1877 Note: if using the --network=host option, the above sysctls are not al‐
1880 lowed.
1881 --systemd=true | false | always
1884 Run container in systemd mode. The default is true.
1885 • true enables systemd mode only when the command executed in‐
1888 side the container is systemd, /usr/sbin/init, /sbin/init or
1889 /usr/local/sbin/init.
1890 • false disables systemd mode.
1892 • always enforces the systemd mode to be enabled.
1894 Running the container in systemd mode causes the following changes:
1898 • Podman mounts tmpfs file systems on the following directories
1901 • /run
1903 • /run/lock
1905 • /tmp
1907 • /sys/fs/cgroup/systemd
1909 • /var/lib/journal
1911 • Podman sets the default stop signal to SIGRTMIN+3.
1915 • Podman sets container_uuid environment variable in the con‐
1917 tainer to the first 32 characters of the container ID.
1918 • Podman does not mount virtual consoles (/dev/tty\d+) when run‐
1920 ning with --privileged.
1921 This allows systemd to run in a confined container without any modifi‐
1925 cations.
1926 Note that on SELinux systems, systemd attempts to write to the cgroup
1929 file system. Containers writing to the cgroup file system are denied by
1930 default. The container_manage_cgroup boolean must be enabled for this
1931 to be allowed on an SELinux separated system.
1932 setsebool -P container_manage_cgroup true
1935 --timeout=seconds
1939 Maximum time a container is allowed to run before conmon sends it the
1940 kill signal. By default containers run until they exit or are stopped
1941 by podman stop.
1942 --tls-verify
1945 Require HTTPS and verify certificates when contacting registries (de‐
1946 fault: true). If explicitly set to true, TLS verification is used. If
1947 set to false, TLS verification is not used. If not specified, TLS ver‐
1948 ification is used unless the target registry is listed as an insecure
1949 registry in containers-registries.conf(5)
1950 --tmpfs=fs
1953 Create a tmpfs mount.
1954 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1957 ple:
1958 $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1961 This command mounts a tmpfs at /tmp within the container. The supported
1965 mount options are the same as the Linux default mount flags. If no op‐
1966 tions are specified, the system uses the following options:
1967 rw,noexec,nosuid,nodev.
1968 --tty, -t
1971 Allocate a pseudo-TTY. The default is false.
1972 When set to true, Podman allocates a pseudo-tty and attach to the stan‐
1975 dard input of the container. This can be used, for example, to run a
1976 throwaway interactive shell.
1977 NOTE: The --tty flag prevents redirection of standard output. It com‐
1980 bines STDOUT and STDERR, it can insert control characters, and it can
1981 hang pipes. This option is only used when run interactively in a termi‐
1982 nal. When feeding input to Podman, use -i only, not -it.
1983 --tz=timezone
1986 Set timezone in container. This flag takes area-based timezones, GMT
1987 time, as well as local, which sets the timezone in the container to
1988 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
1989 Remote connections use local containers.conf for defaults
1990 --uidmap=[flags]container_uid:from_uid[:amount]
1993 Run the container in a new user namespace using the supplied UID map‐
1994 ping. This option conflicts with the --userns and --subuidname options.
1995 This option provides a way to map host UIDs to container UIDs. It can
1996 be passed several times to map different ranges.
1997 The possible values of the optional flags are discussed further down on
2000 this page. The amount value is optional and assumed to be 1 if not
2001 given.
2002 The from_uid value is based upon the user running the command, either
2005 rootful or rootless users.
2006 • rootful user: [flags]container_uid:host_uid[:amount]
2009 • rootless user: [flags]container_uid:intermediate_uid[:amount]
2011 Rootful mappings
2015 When podman create is called by a privileged user, the option --uidmap
2018 works as a direct mapping between host UIDs and container UIDs.
2019 host UID -> container UID
2022 The amount specifies the number of consecutive UIDs that is mapped. If
2025 for example amount is 4 the mapping looks like:
2026 ┌─────────────┬───────────────────┐
2029 │host UID │ container UID │
2030 ├─────────────┼───────────────────┤
2031 │from_uid │ container_uid │
2032 ├─────────────┼───────────────────┤
2033 │from_uid + 1 │ container_uid + 1 │
2034 ├─────────────┼───────────────────┤
2035 │from_uid + 2 │ container_uid + 2 │
2036 ├─────────────┼───────────────────┤
2037 │from_uid + 3 │ container_uid + 3 │
2038 └─────────────┴───────────────────┘
2039 Rootless mappings
2041 When podman create is called by an unprivileged user (i.e. running
2044 rootless), the value from_uid is interpreted as an "intermediate UID".
2045 In the rootless case, host UIDs are not mapped directly to container
2046 UIDs. Instead the mapping happens over two mapping steps:
2047 host UID -> intermediate UID -> container UID
2050 The --uidmap option only influences the second mapping step.
2053 The first mapping step is derived by Podman from the contents of the
2056 file /etc/subuid and the UID of the user calling Podman.
2057 First mapping step:
2060 ┌────────────────────┬──────────────────┐
2063 │host UID │ intermediate UID │
2064 ├────────────────────┼──────────────────┤
2065 │UID for Podman user │ 0 │
2066 ├────────────────────┼──────────────────┤
2067 │1st subordinate UID │ 1 │
2068 ├────────────────────┼──────────────────┤
2069 │2nd subordinate UID │ 2 │
2070 ├────────────────────┼──────────────────┤
2071 │3rd subordinate UID │ 3 │
2072 ├────────────────────┼──────────────────┤
2073 │nth subordinate UID │ n │
2074 └────────────────────┴──────────────────┘
2075 To be able to use intermediate UIDs greater than zero, the user needs
2077 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
2078 The second mapping step is configured with --uidmap.
2081 If for example amount is 5 the second mapping step looks like:
2084 ┌─────────────────┬───────────────────┐
2087 │intermediate UID │ container UID │
2088 ├─────────────────┼───────────────────┤
2089 │from_uid │ container_uid │
2090 ├─────────────────┼───────────────────┤
2091 │from_uid + 1 │ container_uid + 1 │
2092 ├─────────────────┼───────────────────┤
2093 │from_uid + 2 │ container_uid + 2 │
2094 ├─────────────────┼───────────────────┤
2095 │from_uid + 3 │ container_uid + 3 │
2096 ├─────────────────┼───────────────────┤
2097 │from_uid + 4 │ container_uid + 4 │
2098 └─────────────────┴───────────────────┘
2099 When running as rootless, Podman uses all the ranges configured in the
2101 /etc/subuid file.
2102 The current user ID is mapped to UID=0 in the rootless user namespace.
2105 Every additional range is added sequentially afterward:
2106 ┌──────────────────────┬─────────────────────────┬──────────────────────┐
2109 │host │ rootless user namespace │ length │
2110 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2111 │$UID │ 0 │ 1 │
2112 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2113 │1 │ $FIRST_RANGE_ID │ $FIRST_RANGE_LENGTH │
2114 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2115 │1+$FIRST_RANGE_LENGTH │ $SECOND_RANGE_ID │ $SECOND_RANGE_LENGTH │
2116 └──────────────────────┴─────────────────────────┴──────────────────────┘
2117 Referencing a host ID from the parent namespace
2119 As a rootless user, the given host ID in --uidmap or --gidmap is mapped
2122 from the intermediate namespace generated by Podman. Sometimes it is
2123 desirable to refer directly at the host namespace. It is possible to
2124 manually do so, by running podman unshare cat /proc/self/gid_map, find‐
2125 ing the desired host id at the second column of the output, and getting
2126 the corresponding intermediate id from the first column.
2127 Podman can perform all that by preceding the host id in the mapping
2130 with the @ symbol. For instance, by specifying --gidmap 100000:@2000:1,
2131 podman will look up the intermediate id corresponding to host id 2000
2132 and it will map the found intermediate id to the container id 100000.
2133 The given host id must have been subordinated (otherwise it would not
2134 be mapped into the intermediate space in the first place).
2135 If the length is greater than one, for instance with --gidmap
2138 100000:@2000:2, Podman will map host ids 2000 and 2001 to 100000 and
2139 100001, respectively, regardless of how the intermediate mapping is de‐
2140 fined.
2141 Extending previous mappings
2144 Some mapping modifications may be cumbersome. For instance, a user
2147 starts with a mapping such as --gidmap="0:0:65000", that needs to be
2148 changed such as the parent id 1000 is mapped to container id 100000 in‐
2149 stead, leaving container id 1 unassigned. The corresponding --gidmap
2150 becomes --gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1".
2151 This notation can be simplified using the + flag, that takes care of
2154 breaking previous mappings removing any conflicting assignment with the
2155 given mapping. The flag is given before the container id as follows:
2156 --gidmap="0:0:65000" --gidmap="+100000:1:1"
2157 ┌─────┬─────────────┬─────────────────────────────┐
2160 │Flag │ Example │ Description │
2161 ├─────┼─────────────┼─────────────────────────────┤
2162 │+ │ +100000:1:1 │ Extend the previous mapping │
2163 └─────┴─────────────┴─────────────────────────────┘
2164 This notation leads to gaps in the assignment, so it may be convenient
2166 to fill those gaps afterwards: --gidmap="0:0:65000"
2167 --gidmap="+100000:1:1" --gidmap="1:65001:1"
2168 One specific use case for this flag is in the context of rootless
2171 users. A rootless user may specify mappings with the + flag as in
2172 --gidmap="+100000:1:1". Podman will then "fill the gaps" starting from
2173 zero with all the remaining intermediate ids. This is convenient when a
2174 user wants to map a specific intermediate id to a container id, leaving
2175 the rest of subordinate ids to be mapped by Podman at will.
2176 Passing only one of --uidmap or --gidmap
2179 Usually, subordinated user and group ids are assigned simultaneously,
2182 and for any user the subordinated user ids match the subordinated group
2183 ids. For convenience, if only one of --uidmap or --gidmap is given,
2184 podman assumes the mapping refers to both UIDs and GIDs and applies the
2185 given mapping to both. If only one value of the two needs to be
2186 changed, the mappings should include the u or the g flags to specify
2187 that they only apply to UIDs or GIDs and should not be copied over.
2188 ┌─────┬───────────────┬─────────────────────┐
2191 │flag │ Example │ Description │
2192 ├─────┼───────────────┼─────────────────────┤
2193 │u │ u20000:2000:1 │ The mapping only │
2194 │ │ │ applies to UIDs │
2195 ├─────┼───────────────┼─────────────────────┤
2196 │g │ g10000:1000:1 │ The mapping only │
2197 │ │ │ applies to GIDs │
2198 └─────┴───────────────┴─────────────────────┘
2199 For instance given the command
2201 podman create --gidmap "0:0:1000" --gidmap "g2000:2000:1"
2204 Since no --uidmap is given, the --gidmap is copied to --uidmap, giving
2208 a command equivalent to
2209 podman create --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"
2212 The --gidmap "g2000:2000:1" used the g flag and therefore it was not
2216 copied to --uidmap.
2217 Rootless mapping of additional host GIDs
2220 A rootless user may desire to map a specific host group that has al‐
2223 ready been subordinated within /etc/subgid without specifying the rest
2224 of the mapping.
2225 This can be done with --gidmap "+gcontainer_gid:@host_gid"
2228 Where:
2231 • The host GID is given through the @ symbol
2234 • The mapping of this GID is not copied over to --usermap thanks
2236 to the g flag.
2237 • The rest of the container IDs will be mapped starting from 0
2239 to n, with all the remaining subordinated GIDs, thanks to the
2240 + flag.
2241 For instance, if a user belongs to the group 2000 and that group is
2245 subordinated to that user (with usermod --add-subgids 2000-2000 $USER),
2246 the user can map the group into the container with:
2247 --gidmap=+g100000:@2000.
2248 If this mapping is combined with the option, --group-add=keep-groups,
2251 the process in the container will belong to group 100000, and files be‐
2252 longing to group 2000 in the host will appear as being owned by group
2253 100000 inside the container.
2254 podman run --group-add=keep-groups --gidmap="+g100000:@2000" ...
2257 No subordinate UIDs
2261 Even if a user does not have any subordinate UIDs in /etc/subuid,
2264 --uidmap can be used to map the normal UID of the user to a container
2265 UID by running podman create --uidmap $container_uid:0:1 --user $con‐
2266 tainer_uid ....
2267 Pods
2270 The --uidmap option cannot be called in conjunction with the --pod op‐
2273 tion as a uidmap cannot be set on the container level when in a pod.
2274 --ulimit=option
2277 Ulimit options. Sets the ulimits values inside of the container.
2278 --ulimit with a soft and hard limit in the format =[:]. For example:
2281 $ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024
2284 Use host to copy the current configuration from the host.
2287 Don't use nproc with the ulimit flag as Linux uses nproc to set the
2290 maximum number of processes available to a user, not to a container.
2291 Use the --pids-limit option to modify the cgroup control to limit the
2294 number of processes within a container.
2295 --umask=umask
2298 Set the umask inside the container. Defaults to 0022. Remote connec‐
2299 tions use local containers.conf for defaults
2300 --unsetenv=env
2303 Unset default environment variables for the container. Default environ‐
2304 ment variables include variables provided natively by Podman, environ‐
2305 ment variables configured by the image, and environment variables from
2306 containers.conf.
2307 --unsetenv-all
2310 Unset all default environment variables for the container. Default en‐
2311 vironment variables include variables provided natively by Podman, en‐
2312 vironment variables configured by the image, and environment variables
2313 from containers.conf.
2314 --user, -u=user[:group]
2317 Sets the username or UID used and, optionally, the groupname or GID for
2318 the specified command. Both user and group may be symbolic or numeric.
2319 Without this argument, the command runs as the user specified in the
2322 container image. Unless overridden by a USER command in the Container‐
2323 file or by a value passed to this option, this user generally defaults
2324 to root.
2325 When a user namespace is not in use, the UID and GID used within the
2328 container and on the host match. When user namespaces are in use, how‐
2329 ever, the UID and GID in the container may correspond to another UID
2330 and GID on the host. In rootless containers, for example, a user name‐
2331 space is always used, and root in the container by default corresponds
2332 to the UID and GID of the user invoking Podman.
2333 --userns=mode
2336 Set the user namespace mode for the container.
2337 If --userns is not set, the default value is determined as follows. -
2340 If --pod is set, --userns is ignored and the user namespace of the pod
2341 is used. - If the environment variable PODMAN_USERNS is set its value
2342 is used. - If userns is specified in containers.conf this value is
2343 used. - Otherwise, --userns=host is assumed.
2344 --userns="" (i.e., an empty string) is an alias for --userns=host.
2347 This option is incompatible with --gidmap, --uidmap, --subuidname and
2350 --subgidname.
2351 Rootless user --userns=Key mappings:
2354 ┌────────────────────────┬───────────┬─────────────────────┐
2357 │Key │ Host User │ Container User │
2358 ├────────────────────────┼───────────┼─────────────────────┤
2359 │auto │ $UID │ nil (Host User UID │
2360 │ │ │ is not mapped into │
2361 │ │ │ container.) │
2362 ├────────────────────────┼───────────┼─────────────────────┤
2363 │host │ $UID │ 0 (Default User ac‐ │
2364 │ │ │ count mapped to │
2365 │ │ │ root user in con‐ │
2366 │ │ │ tainer.) │
2367 ├────────────────────────┼───────────┼─────────────────────┤
2368 │keep-id │ $UID │ $UID (Map user ac‐ │
2369 │ │ │ count to same UID │
2370 │ │ │ within container.) │
2371 ├────────────────────────┼───────────┼─────────────────────┤
2372 │keep-id:uid=200,gid=210 │ $UID │ 200:210 (Map user │
2373 │ │ │ account to speci‐ │
2374 │ │ │ fied UID, GID value │
2375 │ │ │ within container.) │
2376 ├────────────────────────┼───────────┼─────────────────────┤
2377 │nomap │ $UID │ nil (Host User UID │
2378 │ │ │ is not mapped into │
2379 │ │ │ container.) │
2380 └────────────────────────┴───────────┴─────────────────────┘
2381 Valid mode values are:
2383 auto[:OPTIONS,...]: automatically create a unique user namespace.
2386 The --userns=auto flag requires that the user name containers be speci‐
2389 fied in the /etc/subuid and /etc/subgid files, with an unused range of
2390 subordinate user IDs that Podman containers are allowed to allocate.
2391 See subuid(5).
2392 Example: containers:2147483647:2147483648.
2395 Podman allocates unique ranges of UIDs and GIDs from the containers
2398 subordinate user IDs. The size of the ranges is based on the number of
2399 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
2400 den with the size option.
2401 The option --userns=keep-id uses all the subuids and subgids of the
2404 user. The option --userns=nomap uses all the subuids and subgids of
2405 the user except the user's own ID. Using --userns=auto when starting
2406 new containers does not work as long as any containers exist that were
2407 started with --userns=keep-id or --userns=nomap.
2408 Valid auto options:
2411 • gidmapping=CONTAINER_GID:HOST_GID:SIZE: to force a GID mapping
2414 to be present in the user namespace.
2415 • size=SIZE: to specify an explicit size for the automatic user
2417 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
2418 fied, auto estimates a size for the user namespace.
2419 • uidmapping=CONTAINER_UID:HOST_UID:SIZE: to force a UID mapping
2421 to be present in the user namespace.
2422 container:id: join the user namespace of the specified container.
2426 host or "" (empty string): run in the user namespace of the caller. The
2429 processes running in the container have the same privileges on the host
2430 as any other process launched by the calling user.
2431 keep-id: creates a user namespace where the current user's UID:GID are
2434 mapped to the same values in the container. For containers created by
2435 root, the current mapping is created into a new user namespace.
2436 Valid keep-id options:
2439 • uid=UID: override the UID inside the container that is used to
2442 map the current user to.
2443 • gid=GID: override the GID inside the container that is used to
2445 map the current user to.
2446 nomap: creates a user namespace where the current rootless user's
2450 UID:GID are not mapped into the container. This option is not allowed
2451 for containers created by the root user.
2452 ns:namespace: run the container in the given existing user namespace.
2455 --uts=mode
2458 Set the UTS namespace mode for the container. The following values are
2459 supported:
2460 • host: use the host's UTS namespace inside the container.
2463 • private: create a new namespace for the container (default).
2465 • ns:[path]: run the container in the given existing UTS name‐
2467 space.
2468 • container:[container]: join the UTS namespace of the specified
2470 container.
2471 --variant=VARIANT
2475 Use VARIANT instead of the default architecture variant of the con‐
2476 tainer image. Some images can use multiple variants of the arm archi‐
2477 tectures, such as arm/v5 and arm/v7.
2478 --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2481 Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Pod‐
2482 man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2483 man container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR mounts the
2484 named volume from the host into the container. If no such named volume
2485 exists, Podman creates one. If no source is given, the volume is cre‐
2486 ated as an anonymously named volume with a randomly generated name, and
2487 is removed when the container is removed via the --rm flag or the pod‐
2488 man rm --volumes command.
2489 (Note when using the remote client, including Mac and Windows (exclud‐
2492 ing WSL2) machines, the volumes are mounted from the remote server, not
2493 necessarily the client machine.)
2494 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2497 • rw|ro
2500 • z|Z
2502 • [O]
2504 • [U]
2506 • [no]copy
2508 • [no]dev
2510 • [no]exec
2512 • [no]suid
2514 • [r]bind
2516 • [r]shared|[r]slave|[r]private[r]unbindable
2518 • idmap[=options]
2520 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2524 ume is mounted into the container at this directory.
2525 If a volume source is specified, it must be a path on the host or the
2528 name of a named volume. Host paths are allowed to be absolute or rela‐
2529 tive; relative paths are resolved relative to the directory Podman is
2530 run in. If the source does not exist, Podman returns an error. Users
2531 must pre-create the source files or directories.
2532 Any source that does not begin with a . or / is treated as the name of
2535 a named volume. If a volume with that name does not exist, it is cre‐
2536 ated. Volumes created with names are not anonymous, and they are not
2537 removed by the --rm option and the podman rm --volumes command.
2538 Specify multiple -v options to mount one or more volumes into a con‐
2541 tainer.
2542 Write Protected Volume Mounts
2545 Add :ro or :rw option to mount a volume in read-only or read-write
2548 mode, respectively. By default, the volumes are mounted read-write.
2549 See examples.
2550 Chowning Volume Mounts
2553 By default, Podman does not change the owner and group of source volume
2556 directories mounted into containers. If a container is created in a new
2557 user namespace, the UID and GID in the container may correspond to an‐
2558 other UID and GID on the host.
2559 The :U suffix tells Podman to use the correct host UID and GID based on
2562 the UID and GID within the container, to change recursively the owner
2563 and group of the source volume. Chowning walks the file system under
2564 the volume and changes the UID/GID on each file. If the volume has
2565 thousands of inodes, this process takes a long time, delaying the start
2566 of the container.
2567 Warning use with caution since this modifies the host filesystem.
2570 Labeling Volume Mounts
2573 Labeling systems like SELinux require that proper labels are placed on
2576 volume content mounted into a container. Without a label, the security
2577 system might prevent the processes running inside the container from
2578 using the content. By default, Podman does not change the labels set by
2579 the OS.
2580 To change a label in the container context, add either of two suffixes
2583 :z or :Z to the volume mount. These suffixes tell Podman to relabel
2584 file objects on the shared volumes. The z option tells Podman that two
2585 or more containers share the volume content. As a result, Podman labels
2586 the content with a shared content label. Shared volume labels allow all
2587 containers to read/write content. The Z option tells Podman to label
2588 the content with a private unshared label Only the current container
2589 can use a private volume. Relabeling walks the file system under the
2590 volume and changes the label on each file, if the volume has thousands
2591 of inodes, this process takes a long time, delaying the start of the
2592 container. If the volume was previously relabeled with the z option,
2593 Podman is optimized to not relabel a second time. If files are moved
2594 into the volume, then the labels can be manually change with the chcon
2595 -R container_file_t PATH command.
2596 Note: Do not relabel system files and directories. Relabeling system
2599 content might cause other confined services on the machine to fail.
2600 For these types of containers we recommend disabling SELinux separa‐
2601 tion. The option --security-opt label=disable disables SELinux separa‐
2602 tion for the container. For example if a user wanted to volume mount
2603 their entire home directory into a container, they need to disable
2604 SELinux separation.
2605 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2608 Overlay Volume Mounts
2612 The :O flag tells Podman to mount the directory from the host as a tem‐
2615 porary storage using the overlay file system. The container processes
2616 can modify content within the mountpoint which is stored in the con‐
2617 tainer storage in a separate directory. In overlay terms, the source
2618 directory is the lower, and the container storage directory is the up‐
2619 per. Modifications to the mount point are destroyed when the container
2620 finishes executing, similar to a tmpfs mount point being unmounted.
2621 For advanced users, the overlay option also supports custom non-
2624 volatile upperdir and workdir for the overlay mount. Custom upperdir
2625 and workdir can be fully managed by the users themselves, and Podman
2626 does not remove it on lifecycle completion. Example :O,up‐
2627 perdir=/some/upper,workdir=/some/work
2628 Subsequent executions of the container sees the original source direc‐
2631 tory content, any changes from previous container executions no longer
2632 exist.
2633 One use case of the overlay mount is sharing the package cache from the
2636 host into the container to allow speeding up builds.
2637 Note: The O flag conflicts with other options listed above.
2640 Content mounted into the container is labeled with the private label.
2643 On SELinux systems, labels in the source directory must be read‐
2644 able by the container label. Usually containers can read/execute con‐
2645 tainer_share_t and can read/write container_file_t. If unable to change
2646 the labels on a source volume, SELinux container separation must be
2647 disabled for the container to work.
2648 - Do not modify the source directory mounted into the container
2649 with an overlay mount, it can cause unexpected failures. Only modify
2650 the directory after the container finishes running.
2651 Mounts propagation
2654 By default bind mounted volumes are private. That means any mounts done
2657 inside the container is not visible on host and vice versa. One can
2658 change this behavior by specifying a volume mount propagation property.
2659 Making a volume shared mounts done under that volume inside the con‐
2660 tainer is visible on host and vice versa. Making a volume slave enables
2661 only one way mount propagation and that is mounts done on host under
2662 that volume is visible inside container but not the other way around.
2663 [1] ⟨#Footnote1⟩
2664 To control mount propagation property of a volume one can use the
2667 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2668 Propagation property can be specified only for bind mounted volumes and
2669 not for internal volumes or named volumes. For mount propagation to
2670 work the source mount point (the mount point where source dir is
2671 mounted on) has to have the right propagation properties. For shared
2672 volumes, the source mount point has to be shared. And for slave vol‐
2673 umes, the source mount point has to be either shared or slave. [1]
2674 ⟨#Footnote1⟩
2675 To recursively mount a volume and all of its submounts into a con‐
2678 tainer, use the rbind option. By default the bind option is used, and
2679 submounts of the source directory is not mounted into the container.
2680 Mounting the volume with a copy option tells podman to copy content
2683 from the underlying destination directory onto newly created internal
2684 volumes. The copy only happens on the initial creation of the volume.
2685 Content is not copied up when the volume is subsequently used on dif‐
2686 ferent containers. The copy option is ignored on bind mounts and has no
2687 effect.
2688 Mounting volumes with the nosuid options means that SUID executables on
2691 the volume can not be used by applications to change their privilege.
2692 By default volumes are mounted with nosuid.
2693 Mounting the volume with the noexec option means that no executables on
2696 the volume can be executed within the container.
2697 Mounting the volume with the nodev option means that no devices on the
2700 volume can be used by processes within the container. By default vol‐
2701 umes are mounted with nodev.
2702 If the HOST-DIR is a mount point, then dev, suid, and exec options are
2705 ignored by the kernel.
2706 Use df HOST-DIR to figure out the source mount, then use findmnt -o
2709 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2710 ties of source mount. If findmnt[4m(1) utility is not available, then one
2711 can look at the mount entry for the source mount point in
2712 /proc/self/mountinfo. Look at the "optional fields" and see if any
2713 propagation properties are specified. In there, shared:N means the
2714 mount is shared, master:N means mount is slave, and if nothing is
2715 there, the mount is private. [1] ⟨#Footnote1⟩
2716 To change propagation properties of a mount point, use mount(8) com‐
2719 mand. For example, if one wants to bind mount source directory /foo,
2720 one can do mount --bind /foo /foo and mount --make-private --make-
2721 shared /foo. This converts /foo into a shared mount point. Alterna‐
2722 tively, one can directly change propagation properties of source mount.
2723 Say / is source mount for /foo, then use mount --make-shared / to con‐
2724 vert / into a shared mount.
2725 Note: if the user only has access rights via a group, accessing the
2728 volume from inside a rootless container fails.
2729 Idmapped mount
2732 If idmap is specified, create an idmapped mount to the target user
2735 namespace in the container. The idmap option supports a custom mapping
2736 that can be different than the user namespace used by the container.
2737 The mapping can be specified after the idmap option like:
2738 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
2739 value is the start of the backing file system IDs that are mapped to
2740 the second value on the host. The length of this mapping is given in
2741 the third value. Multiple ranges are separated with #.
2742 Use the --group-add keep-groups option to pass the user's supplementary
2745 group access into the container.
2746 --volumes-from=CONTAINER[:OPTIONS]
2749 Mount volumes from the specified container(s). Used to share volumes
2750 between containers. The options is a comma-separated list with the fol‐
2751 lowing available elements:
2752 • rw|ro
2755 • z
2757 Mounts already mounted volumes from a source container onto another
2761 container. CONTAINER may be a name or ID. To share a volume, use the
2762 --volumes-from option when running the target container. Volumes can be
2763 shared even if the source container is not running.
2764 By default, Podman mounts the volumes in the same mode (read-write or
2767 read-only) as it is mounted in the source container. This can be
2768 changed by adding a ro or rw option.
2769 Labeling systems like SELinux require that proper labels are placed on
2772 volume content mounted into a container. Without a label, the security
2773 system might prevent the processes running inside the container from
2774 using the content. By default, Podman does not change the labels set by
2775 the OS.
2776 To change a label in the container context, add z to the volume mount.
2779 This suffix tells Podman to relabel file objects on the shared volumes.
2780 The z option tells Podman that two entities share the volume content.
2781 As a result, Podman labels the content with a shared content label.
2782 Shared volume labels allow all containers to read/write content.
2783 If the location of the volume from the source container overlaps with
2786 data residing on a target container, then the volume hides that data on
2787 the target.
2788 --workdir, -w=dir
2791 Working directory inside the container.
2792 The default working directory for running binaries within a container
2795 is the root directory (/). The image developer can set a different de‐
2796 fault with the WORKDIR instruction. The operator can override the work‐
2797 ing directory by using the -w option.
2798
2801 Create a container using a local image
2802 $ podman create alpine ls
2803 Create a container using a local image and annotate it
2807 $ podman create --annotation HELLO=WORLD alpine ls
2808 Create a container using a local image, allocating a pseudo-TTY, keeping
2812 stdin open and name it myctr
2813 podman create -t -i --name myctr alpine ls
2814 Set UID/GID mapping in a new user namespace
2818 Running a container in a new user namespace requires a mapping of the
2819 UIDs and GIDs from the host.
2820 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2823 Setting automatic user namespace separated containers
2827 # podman create --userns=auto:size=65536 ubi8-init
2828 Configure timezone in a container
2832 $ podman create --tz=local alpine date
2833 $ podman create --tz=Asia/Shanghai alpine date
2834 $ podman create --tz=US/Eastern alpine date
2835 Adding dependency containers
2839 Podman makes sure the first container, container1, is running before
2840 the second container (container2) is started.
2841 $ podman create --name container1 -t -i fedora bash
2844 $ podman create --name container2 --requires container1 -t -i fedora bash
2845 $ podman start --attach container2
2846 Multiple containers can be required.
2850 $ podman create --name container1 -t -i fedora bash
2853 $ podman create --name container2 -t -i fedora bash
2854 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2855 $ podman start --attach container3
2856 Exposing shared libraries inside of container as read-only using a glob
2860 $ podman create --mount type=glob,src=/usr/lib64/libnvidia\*,ro -i -t fedora /bin/bash
2861 Configure keep supplemental groups for access to volume
2865 $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2866 Configure execution domain for containers using personality flag
2870 $ podman create --name container1 --personality=LINUX32 fedora bash
2871 Create a container with external rootfs mounted as an overlay
2875 $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2876 Create a container connected to two networks (called net1 and net2) with a
2880 static ip
2881 $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2882 Rootless Containers
2886 Podman runs as a non-root user on most systems. This feature requires
2887 that a new enough version of shadow-utils be installed. The shadow-
2888 utils package must include the newuidmap and newgidmap executables.
2889 In order for users to run rootless, there must be an entry for their
2892 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2893 user namespace.
2894 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2897 packages are installed. The fuse-overlayfs package provides a
2898 userspace overlay storage driver, otherwise users need to use the vfs
2899 storage driver, which can be disk space expensive and less performant
2900 than other drivers.
2901 To enable VPN on the container, slirp4netns or pasta needs to be speci‐
2904 fied; without either, containers need to be run with the --network=host
2905 flag.
2906
2909 Environment variables within containers can be set using multiple dif‐
2910 ferent options: This section describes the precedence.
2911 Precedence order (later entries override earlier entries):
2914 • --env-host : Host environment of the process executing Podman
2917 is added.
2918 • --http-proxy: By default, several environment variables are
2920 passed in from the host, such as http_proxy and no_proxy. See
2921 --http-proxy for details.
2922 • Container image : Any environment variables specified in the
2924 container image.
2925 • --env-file : Any environment variables specified via env-
2927 files. If multiple files specified, then they override each
2928 other in order of entry.
2929 • --env : Any environment variables specified overrides previous
2931 settings.
2932 Create containers and set the environment ending with a *. The trail‐
2936 ing * glob functionality is only active when no value is specified:
2937 $ export ENV1=a
2940 $ podman create --name ctr1 --env 'ENV*' alpine env
2941 $ podman start --attach ctr1 | grep ENV
2942 ENV1=a
2943 $ podman create --name ctr2 --env 'ENV*=b' alpine env
2944 $ podman start --attach ctr2 | grep ENV
2945 ENV*=b
2946
2950 When Podman starts a container it actually executes the conmon program,
2951 which then executes the OCI Runtime. Conmon is the container monitor.
2952 It is a small program whose job is to watch the primary process of the
2953 container, and if the container dies, save the exit code. It also
2954 holds open the tty of the container, so that it can be attached to
2955 later. This is what allows Podman to run in detached mode (back‐
2956 grounded), so Podman can exit but conmon continues to run. Each con‐
2957 tainer has their own instance of conmon. Conmon waits for the container
2958 to exit, gathers and saves the exit code, and then launches a Podman
2959 process to complete the container cleanup, by shutting down the network
2960 and storage. For more information about conmon, see the conmon(8) man
2961 page.
2962
2965 /etc/subuid /etc/subgid
2966 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2969 age location of downloaded container images. Podman defaults to use
2970 /var/tmp.
2971
2974 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2975 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
2976 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
2977 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
2978 slirp4netns(1), pasta(1), fuse-overlayfs(1), proc(5), conmon(8), per‐
2979 sonality(2)
2980
2983 October 2017, converted from Docker documentation to Podman by Dan
2984 Walsh for Podman <dwalsh@redhat.com>
2985 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2988 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2991 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2994
2997 1: The Podman project is committed to inclusivity, a core value of open
2998 source. The master and slave mount propagation terminology used here is
2999 problematic and divisive, and needs to be changed. However, these terms
3000 are currently used within the Linux kernel and must be used as-is at
3001 this time. When the kernel maintainers rectify this usage, Podman will
3002 follow suit immediately.
3003 podman-create(1)