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
46 $ podman create dir:/tmp/fedora echo hello
47 docker://docker-reference (Default)
51 An image reference stored in a remote container image registry. Ex‐
52 ample: "quay.io/podman/stable:latest". The reference can include a
53 path to a specific registry; if it does not, the registries listed in
54 registries.conf is queried to find a matching image. By default, cre‐
55 dentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
56 ers/auth.json by default) is used to authenticate; otherwise it falls
57 back to using credentials in $HOME/.docker/config.json.
58 $ podman create registry.fedoraproject.org/fedora:latest echo hello
60 docker-archive:path[:docker-reference] An image stored in the docker
64 save formatted file. docker-reference is only used when creating such a
65 file, and it must not contain a digest.
66 $ podman save --format docker-archive fedora -o /tmp/fedora
68 $ podman create docker-archive:/tmp/fedora echo hello
69 docker-daemon:docker-reference
73 An image in docker-reference format stored in the docker daemon in‐
74 ternal storage. The docker-reference can also be an image ID (docker-
75 daemon:algo:digest).
76 $ sudo docker pull fedora
78 $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
79 oci-archive:path:tag
83 An image in a directory compliant with the "Open Container Image Lay‐
84 out Specification" at the specified path and specified with a tag.
85 $ podman save --format oci-archive fedora -o /tmp/fedora
87 $ podman create oci-archive:/tmp/fedora echo hello
88
92 --add-host=host:ip
93 Add a custom host-to-IP mapping (host:ip)
94 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
97 tion can be set multiple times. Conflicts with the --no-hosts option.
98 --annotation=key=value
101 Add an annotation to the container. This option can be set multiple
102 times.
103 --arch=ARCH
106 Override the architecture, defaults to hosts, of the image to be
107 pulled. For example, arm. Unless overridden, subsequent lookups of the
108 same image in the local storage matches this architecture, regardless
109 of the host.
110 --attach, -a=stdin | stdout | stderr
113 Attach to STDIN, STDOUT or STDERR.
114 In foreground mode (the default when -d is not specified), podman run
117 can start the process in the container and attach the console to the
118 process's standard input, output, and error. It can even pretend to be
119 a TTY (this is what most command-line executables expect) and pass
120 along signals. The -a option can be set for each of stdin, stdout, and
121 stderr.
122 --authfile=path
125 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
126 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
127 dows/macOS. The file is created by podman login. If the authorization
128 state is not found there, $HOME/.docker/config.json is checked, which
129 is set using docker login.
130 Note: There is also the option to override the default path of the au‐
133 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
134 able. This can be done with export REGISTRY_AUTH_FILE=path.
135 --blkio-weight=weight
138 Block IO relative weight. The weight is a value between 10 and 1000.
139 This option is not supported on cgroups V1 rootless systems.
142 --blkio-weight-device=device:weight
145 Block IO relative device weight.
146 --cap-add=capability
149 Add Linux capabilities.
150 --cap-drop=capability
153 Drop Linux capabilities.
154 --cgroup-conf=KEY=VALUE
157 When running on cgroup v2, specify the cgroup file to write to and its
158 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
159 ory.high limit to 1GB.
160 --cgroup-parent=path
163 Path to cgroups under which the cgroup for the container is created. If
164 the path is not absolute, the path is considered to be relative to the
165 cgroups path of the init process. Cgroups are created if they do not
166 already exist.
167 --cgroupns=mode
170 Set the cgroup namespace mode for the container.
171 • host: use the host's cgroup namespace inside the container.
174 • container:id: join the namespace of the specified container.
176 • private: create a new cgroup namespace.
178 • ns:path: join the namespace at the specified path.
180 If the host uses cgroups v1, the default is set to host. On cgroups v2,
184 the default is private.
185 --cgroups=how
188 Determines whether the container creates CGroups.
189 Default is enabled.
192 The enabled option creates a new cgroup under the cgroup-parent. The
195 disabled option forces the container to not create CGroups, and thus
196 conflicts with CGroup options (--cgroupns and --cgroup-parent). The
197 no-conmon option disables a new CGroup only for the conmon process.
198 The split option splits the current CGroup in two sub-cgroups: one for
199 conmon and one for the container payload. It is not possible to set
200 --cgroup-parent with split.
201 --chrootdirs=path
204 Path to a directory inside the container that is treated as a chroot
205 directory. Any Podman managed file (e.g., /etc/resolv.conf,
206 /etc/hosts, etc/hostname) that is mounted into the root directory is
207 mounted into that location as well. Multiple directories are separated
208 with a comma.
209 --cidfile=file
212 Write the container ID to file. The file is removed along with the
213 container, except when used with podman --remote run on detached con‐
214 tainers.
215 --conmon-pidfile=file
218 Write the pid of the conmon process to a file. As conmon runs in a sep‐
219 arate process than Podman, this is necessary when using systemd to
220 restart Podman containers. (This option is not available with the re‐
221 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
222 chines)
223 --cpu-period=limit
226 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
227 duration in microseconds. Once the container's CPU quota is used up, it
228 will not be scheduled to run until the current period ends. Defaults to
229 100000 microseconds.
230 On some systems, changing the resource limits may not be allowed for
233 non-root users. For more details, see https://github.com/contain‐
234 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
235 source-limits-fails-with-a-permissions-error
236 This option is not supported on cgroups V1 rootless systems.
239 --cpu-quota=limit
242 Limit the CPU Completely Fair Scheduler (CFS) quota.
243 Limit the container's CPU usage. By default, containers run with the
246 full CPU resource. The limit is a number in microseconds. If a number
247 is provided, the container is allowed to use that much CPU time until
248 the CPU period ends (controllable via --cpu-period).
249 On some systems, changing the resource limits may not be allowed for
252 non-root users. For more details, see https://github.com/contain‐
253 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
254 source-limits-fails-with-a-permissions-error
255 This option is not supported on cgroups V1 rootless systems.
258 --cpu-rt-period=microseconds
261 Limit the CPU real-time period in microseconds.
262 Limit the container's Real Time CPU usage. This option tells the kernel
265 to restrict the container's Real Time CPU usage to the period speci‐
266 fied.
267 This option is only supported on cgroups V1 rootful systems.
270 --cpu-rt-runtime=microseconds
273 Limit the CPU real-time runtime in microseconds.
274 Limit the containers Real Time CPU usage. This option tells the kernel
277 to limit the amount of time in a given CPU period Real Time tasks may
278 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
279 this container can consume 95% of available CPU and leave the remaining
280 5% to normal priority tasks.
281 The sum of all runtimes across containers cannot exceed the amount al‐
284 lotted to the parent cgroup.
285 This option is only supported on cgroups V1 rootful systems.
288 --cpu-shares, -c=shares
291 CPU shares (relative weight).
292 By default, all containers get the same proportion of CPU cycles. This
295 proportion can be modified by changing the container's CPU share
296 weighting relative to the combined weight of all the running contain‐
297 ers. Default weight is 1024.
298 The proportion only applies when CPU-intensive processes are running.
301 When tasks in one container are idle, other containers can use the
302 left-over CPU time. The actual amount of CPU time varies depending on
303 the number of containers running on the system.
304 For example, consider three containers, one has a cpu-share of 1024 and
307 two others have a cpu-share setting of 512. When processes in all three
308 containers attempt to use 100% of CPU, the first container receives 50%
309 of the total CPU time. If a fourth container is added with a cpu-share
310 of 1024, the first container only gets 33% of the CPU. The remaining
311 containers receive 16.5%, 16.5% and 33% of the CPU.
312 On a multi-core system, the shares of CPU time are distributed over all
315 CPU cores. Even if a container is limited to less than 100% of CPU
316 time, it can use 100% of each individual CPU core.
317 For example, consider a system with more than three cores. If the con‐
320 tainer C0 is started with --cpu-shares=512 running one process, and an‐
321 other container C1 with --cpu-shares=1024 running two processes, this
322 can result in the following division of CPU shares:
323 ┌────┬───────────┬─────┬──────────────┐
326 │PID │ container │ CPU │ CPU share │
327 ├────┼───────────┼─────┼──────────────┤
328 │100 │ C0 │ 0 │ 100% of CPU0 │
329 ├────┼───────────┼─────┼──────────────┤
330 │101 │ C1 │ 1 │ 100% of CPU1 │
331 ├────┼───────────┼─────┼──────────────┤
332 │102 │ C1 │ 2 │ 100% of CPU2 │
333 └────┴───────────┴─────┴──────────────┘
334 On some systems, changing the resource limits may not be allowed for
336 non-root users. For more details, see https://github.com/contain‐
337 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
338 source-limits-fails-with-a-permissions-error
339 This option is not supported on cgroups V1 rootless systems.
342 --cpus=number
345 Number of CPUs. The default is 0.0 which means no limit. This is short‐
346 hand for --cpu-period and --cpu-quota, therefore the option cannot be
347 specified with --cpu-period or --cpu-quota.
348 On some systems, changing the CPU limits may not be allowed for non-
351 root users. For more details, see https://github.com/containers/pod‐
352 man/blob/main/troubleshooting.md#26-running-containers-with-resource-
353 limits-fails-with-a-permissions-error
354 This option is not supported on cgroups V1 rootless systems.
357 --cpuset-cpus=number
360 CPUs in which to allow execution. Can be specified as a comma-separated
361 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
362 (e.g. 0-3,7,11-15).
363 On some systems, changing the resource limits may not be allowed for
366 non-root users. For more details, see https://github.com/contain‐
367 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
368 source-limits-fails-with-a-permissions-error
369 This option is not supported on cgroups V1 rootless systems.
372 --cpuset-mems=nodes
375 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
376 tive on NUMA systems.
377 If there are four memory nodes on the system (0-3), use --cpuset-
380 mems=0,1 then processes in the container only uses memory from the
381 first two memory nodes.
382 On some systems, changing the resource limits may not be allowed for
385 non-root users. For more details, see https://github.com/contain‐
386 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
387 source-limits-fails-with-a-permissions-error
388 This option is not supported on cgroups V1 rootless systems.
391 --decryption-key=key[:passphrase]
394 The [key[:passphrase]] to be used for decryption of images. Key can
395 point to keys and/or certificates. Decryption is tried with all keys.
396 If the key is protected by a passphrase, it is required to be passed in
397 the argument and omitted otherwise.
398 --device=host-device[:container-device][:permissions]
401 Add a host device to the container. Optional permissions parameter can
402 be used to specify device permissions by combining r for read, w for
403 write, and m for mknod(2).
404 Example: --device=/dev/sdc:/dev/xvdc:rwm.
407 Note: if host-device is a symbolic link then it is resolved first. The
410 container only stores the major and minor numbers of the host device.
411 Podman may load kernel modules required for using the specified device.
414 The devices that Podman loads modules for when necessary are:
415 /dev/fuse.
416 In rootless mode, the new device is bind mounted in the container from
419 the host rather than Podman creating it within the container space. Be‐
420 cause the bind mount retains its SELinux label on SELinux systems, the
421 container can get permission denied when accessing the mounted device.
422 Modify SELinux settings to allow containers to use all device labels
423 via the following command:
424 $ sudo setsebool -P container_use_devices=true
427 Note: if the user only has access rights via a group, accessing the de‐
430 vice from inside a rootless container fails. Use the --group-add keep-
431 groups flag to pass the user's supplementary group access into the con‐
432 tainer.
433 --device-cgroup-rule="type major:minor mode"
436 Add a rule to the cgroup allowed devices list. The rule is expected to
437 be in the format specified in the Linux kernel documentation (Documen‐
438 tation/cgroup-v1/devices.txt):
439 - type: a (all), c (char), or b (block);
440 - major and minor: either a number, or * for all;
441 - mode: a composition of r (read), w (write), and m (mknod(2)).
442 --device-read-bps=path:rate
445 Limit read rate (in bytes per second) from a device (e.g. --device-
446 read-bps=/dev/sda:1mb).
447 On some systems, changing the resource limits may not be allowed for
450 non-root users. For more details, see https://github.com/contain‐
451 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
452 source-limits-fails-with-a-permissions-error
453 This option is not supported on cgroups V1 rootless systems.
456 --device-read-iops=path:rate
459 Limit read rate (in IO operations per second) from a device (e.g. --de‐
460 vice-read-iops=/dev/sda:1000).
461 On some systems, changing the resource limits may not be allowed for
464 non-root users. For more details, see https://github.com/contain‐
465 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
466 source-limits-fails-with-a-permissions-error
467 This option is not supported on cgroups V1 rootless systems.
470 --device-write-bps=path:rate
473 Limit write rate (in bytes per second) to a device (e.g. --device-
474 write-bps=/dev/sda:1mb).
475 On some systems, changing the resource limits may not be allowed for
478 non-root users. For more details, see https://github.com/contain‐
479 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
480 source-limits-fails-with-a-permissions-error
481 This option is not supported on cgroups V1 rootless systems.
484 --device-write-iops=path:rate
487 Limit write rate (in IO operations per second) to a device (e.g. --de‐
488 vice-write-iops=/dev/sda:1000).
489 On some systems, changing the resource limits may not be allowed for
492 non-root users. For more details, see https://github.com/contain‐
493 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
494 source-limits-fails-with-a-permissions-error
495 This option is not supported on cgroups V1 rootless systems.
498 --disable-content-trust
501 This is a Docker-specific option to disable image verification to a
502 container registry and is not supported by Podman. This option is a
503 NOOP and provided solely for scripting compatibility.
504 --dns=ipaddr
507 Set custom DNS servers.
508 This option can be used to override the DNS configuration passed to the
511 container. Typically this is necessary when the host DNS configuration
512 is invalid for the container (e.g., 127.0.0.1). When this is the case
513 the --dns flag is necessary for every run.
514 The special value none can be specified to disable creation of /etc/re‐
517 solv.conf in the container by Podman. The /etc/resolv.conf file in the
518 image is used without changes.
519 This option cannot be combined with --network that is set to none or
522 container:id.
523 --dns-option=option
526 Set custom DNS options. Invalid if using --dns-option with --network
527 that is set to none or container:id.
528 --dns-search=domain
531 Set custom DNS search domains. Invalid if using --dns-search with
532 --network that is set to none or container:id. Use --dns-search=. to
533 remove the search domain.
534 --entrypoint="command" | '["command", arg1 , ...]'
537 Override the default ENTRYPOINT from the image.
538 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
541 what executable to run when the container starts, but it is (purposely)
542 more difficult to override. The ENTRYPOINT gives a container its de‐
543 fault nature or behavior. When the ENTRYPOINT is set, the container
544 runs as if it were that binary, complete with default options. More op‐
545 tions can be passed in via the COMMAND. But, if a user wants to run
546 something else inside the container, the --entrypoint option allows a
547 new ENTRYPOINT to be specified.
548 Specify multi option commands in the form of a json string.
551 --env, -e=env
554 Set environment variables.
555 This option allows arbitrary environment variables that are available
558 for the process to be launched inside of the container. If an environ‐
559 ment variable is specified without a value, Podman checks the host en‐
560 vironment for a value and set the variable only if it is set on the
561 host. As a special case, if an environment variable ending in * is
562 specified without a value, Podman searches the host environment for
563 variables starting with the prefix and adds those variables to the con‐
564 tainer.
565 See ⟨#environment⟩ note below for precedence and examples.
568 --env-file=file
571 Read in a line-delimited file of environment variables.
572 See ⟨#environment⟩ note below for precedence and examples.
575 --env-host
578 Use host environment inside of the container. See Environment note be‐
579 low for precedence. (This option is not available with the remote Pod‐
580 man client, including Mac and Windows (excluding WSL2) machines)
581 --env-merge=env
584 Preprocess default environment variables for the containers. For exam‐
585 ple if image contains environment variable hello=world user can prepro‐
586 cess it using --env-merge hello=${hello}-some so new value is
587 hello=world-some.
588 Please note that if the environment variable hello is not present in
591 the image, then it'll be replaced by an empty string and so using
592 --env-merge hello=${hello}-some would result in the new value of
593 hello=-some, notice the leading - delimiter.
594 --expose=port
597 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
598 port redirection on the host system.
599 --gidmap=[flags]container_uid:from_uid[:amount]
602 Run the container in a new user namespace using the supplied GID map‐
603 ping. This option conflicts with the --userns and --subgidname options.
604 This option provides a way to map host GIDs to container GIDs in the
605 same way as --uidmap maps host UIDs to container UIDs. For details see
606 --uidmap.
607 Note: the --gidmap option cannot be called in conjunction with the
610 --pod option as a gidmap cannot be set on the container level when in a
611 pod.
612 --group-add=group | keep-groups
615 Assign additional groups to the primary user running within the con‐
616 tainer process.
617 • keep-groups is a special flag that tells Podman to keep the
620 supplementary group access.
621 Allows container to use the user's supplementary group access. If file
625 systems or devices are only accessible by the rootless user's group,
626 this flag tells the OCI runtime to pass the group access into the con‐
627 tainer. Currently only available with the crun OCI runtime. Note: keep-
628 groups is exclusive, other groups cannot be specified with this flag.
629 (Not available for remote commands, including Mac and Windows (exclud‐
630 ing WSL2) machines)
631 --group-entry=ENTRY
634 Customize the entry that is written to the /etc/group file within the
635 container when --user is used.
636 The variables $GROUPNAME, $GID, and $USERLIST are automatically re‐
639 placed with their value at runtime if present.
640 --health-cmd="command" | '["command", arg1 , ...]'
643 Set or alter a healthcheck command for a container. The command is a
644 command to be executed inside the container that determines the con‐
645 tainer health. The command is required for other healthcheck options to
646 be applied. A value of none disables existing healthchecks.
647 Multiple options can be passed in the form of a JSON array; otherwise,
650 the command is interpreted as an argument to /bin/sh -c.
651 --health-interval=interval
654 Set an interval for the healthchecks. An interval of disable results in
655 no automatic timer setup. The default is 30s.
656 --health-on-failure=action
659 Action to take once the container transitions to an unhealthy state.
660 The default is none.
661 • none: Take no action.
664 • kill: Kill the container.
666 • restart: Restart the container. Do not combine the restart
668 action with the --restart flag. When running inside of a sys‐
669 temd unit, consider using the kill or stop action instead to
670 make use of systemd's restart policy.
671 • stop: Stop the container.
673 --health-retries=retries
677 The number of retries allowed before a healthcheck is considered to be
678 unhealthy. The default value is 3.
679 --health-start-period=period
682 The initialization time needed for a container to bootstrap. The value
683 can be expressed in time format like 2m3s. The default value is 0s.
684 --health-startup-cmd="command" | '["command", arg1 , ...]'
687 Set a startup healthcheck command for a container. This command is exe‐
688 cuted inside the container and is used to gate the regular healthcheck.
689 When the startup command succeeds, the regular healthcheck begins and
690 the startup healthcheck ceases. Optionally, if the command fails for a
691 set number of attempts, the container is restarted. A startup
692 healthcheck can be used to ensure that containers with an extended
693 startup period are not marked as unhealthy until they are fully
694 started. Startup healthchecks can only be used when a regular
695 healthcheck (from the container's image or the --health-cmd option) is
696 also set.
697 --health-startup-interval=interval
700 Set an interval for the startup healthcheck. An interval of disable re‐
701 sults in no automatic timer setup. The default is 30s.
702 --health-startup-retries=retries
705 The number of attempts allowed before the startup healthcheck restarts
706 the container. If set to 0, the container is never restarted. The de‐
707 fault is 0.
708 --health-startup-success=retries
711 The number of successful runs required before the startup healthcheck
712 succeeds and the regular healthcheck begins. A value of 0 means that
713 any success begins the regular healthcheck. The default is 0.
714 --health-startup-timeout=timeout
717 The maximum time a startup healthcheck command has to complete before
718 it is marked as failed. The value can be expressed in a time format
719 like 2m3s. The default value is 30s.
720 --health-timeout=timeout
723 The maximum time allowed to complete the healthcheck before an interval
724 is considered failed. Like start-period, the value can be expressed in
725 a time format such as 1m22s. The default value is 30s.
726 --help
729 Print usage statement
730 --hostname, -h=name
733 Container host name
734 Sets the container host name that is available inside the container.
737 Can only be used with a private UTS namespace --uts=private (default).
738 If --pod is specified and the pod shares the UTS namespace (default)
739 the pod's hostname is used.
740 --hostuser=name
743 Add a user account to /etc/passwd from the host to the container. The
744 Username or UID must exist on the host system.
745 --http-proxy
748 By default proxy environment variables are passed into the container if
749 set for the Podman process. This can be disabled by setting the value
750 to false. The environment variables passed in include http_proxy,
751 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
752 those. This option is only needed when the host system must use a proxy
753 but the container does not use any proxy. Proxy environment variables
754 specified for the container in any other way overrides the values that
755 have been passed through from the host. (Other ways to specify the
756 proxy for the container include passing the values with the --env flag,
757 or hard coding the proxy environment at container build time.) When
758 used with the remote client it uses the proxy environment variables
759 that are set on the server process.
760 Defaults to true.
763 --image-volume=bind | tmpfs | ignore
766 Tells Podman how to handle the builtin image volumes. Default is bind.
767 • bind: An anonymous named volume is created and mounted into
770 the container.
771 • tmpfs: The volume is mounted onto the container as a tmpfs,
773 which allows the users to create content that disappears when
774 the container is stopped.
775 • ignore: All volumes are just ignored and no action is taken.
777 --init
781 Run an init inside the container that forwards signals and reaps pro‐
782 cesses. The container-init binary is mounted at /run/podman-init.
783 Mounting over /run breaks container execution.
784 --init-ctr=type
787 (Pods only). When using pods, create an init style container, which is
788 run after the infra container is started but before regular pod con‐
789 tainers are started. Init containers are useful for running setup op‐
790 erations for the pod's applications.
791 Valid values for init-ctr type are always or once. The always value
794 means the container runs with each and every pod start, whereas the
795 once value means the container only runs once when the pod is started
796 and then the container is removed.
797 Init containers are only run on pod start. Restarting a pod does not
800 execute any init containers. Furthermore, init containers can only be
801 created in a pod when that pod is not running.
802 --init-path=path
805 Path to the container-init binary.
806 --interactive, -i
809 When set to true, keep stdin open even if not attached. The default is
810 false.
811 --ip=ipv4
814 Specify a static IPv4 address for the container, for example
815 10.88.64.128. This option can only be used if the container is joined
816 to only a single network - i.e., --network=network-name is used at most
817 once - and if the container is not joining another container's network
818 namespace via --network=container:id. The address must be within the
819 network's IP address pool (default 10.88.0.0/16).
820 To specify multiple static IP addresses per container, set multiple
823 networks using the --network option with a static IP address specified
824 for each using the ip mode for that option.
825 --ip6=ipv6
828 Specify a static IPv6 address for the container, for example
829 fd46:db93:aa76:ac37::10. This option can only be used if the container
830 is joined to only a single network - i.e., --network=network-name is
831 used at most once - and if the container is not joining another con‐
832 tainer's network namespace via --network=container:id. The address
833 must be within the network's IPv6 address pool.
834 To specify multiple static IPv6 addresses per container, set multiple
837 networks using the --network option with a static IPv6 address speci‐
838 fied for each using the ip6 mode for that option.
839 --ipc=ipc
842 Set the IPC namespace mode for a container. The default is to create a
843 private IPC namespace.
844 • "": Use Podman's default, defined in containers.conf.
847 • container:id: reuses another container's shared memory, sema‐
849 phores, and message queues
850 • host: use the host's shared memory, semaphores, and message
852 queues inside the container. Note: the host mode gives the
853 container full access to local shared memory and is therefore
854 considered insecure.
855 • none: private IPC namespace, with /dev/shm not mounted.
857 • ns:path: path to an IPC namespace to join.
859 • private: private IPC namespace.
861 • shareable: private IPC namespace with a possibility to share
863 it with other containers.
864 --label, -l=key=value
868 Add metadata to a container.
869 --label-file=file
872 Read in a line-delimited file of labels.
873 --link-local-ip=ip
876 Not implemented.
877 --log-driver=driver
880 Logging driver for the container. Currently available options are k8s-
881 file, journald, none and passthrough, with json-file aliased to k8s-
882 file for scripting compatibility. (Default journald).
883 The podman info command below displays the default log-driver for the
886 system.
887 $ podman info --format '{{ .Host.LogDriver }}'
889 journald
890 The passthrough driver passes down the standard streams (stdin, stdout,
894 stderr) to the container. It is not allowed with the remote Podman
895 client, including Mac and Windows (excluding WSL2) machines, and on a
896 tty, since it is vulnerable to attacks via TIOCSTI.
897 --log-opt=name=value
900 Logging driver specific options.
901 Set custom logging configuration. The following *name*s are supported:
904 path: specify a path to the log file
907 (e.g. --log-opt path=/var/log/container/mycontainer.json);
908 max-size: specify a max size of the log file
911 (e.g. --log-opt max-size=10mb);
912 tag: specify a custom log tag for the container
915 (e.g. --log-opt tag="{{.ImageName}}". It supports the same keys as
916 podman inspect --format. This option is currently supported only by
917 the journald log driver.
918 --mac-address=address
921 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
922 option can only be used if the container is joined to only a single
923 network - i.e., --network=network-name is used at most once - and if
924 the container is not joining another container's network namespace via
925 --network=container:id.
926 Remember that the MAC address in an Ethernet network must be unique.
929 The IPv6 link-local address is based on the device's MAC address ac‐
930 cording to RFC4862.
931 To specify multiple static MAC addresses per container, set multiple
934 networks using the --network option with a static MAC address specified
935 for each using the mac mode for that option.
936 --memory, -m=number[unit]
939 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
940 g (gibibytes).
941 Allows the memory available to a container to be constrained. If the
944 host supports swap memory, then the -m memory setting can be larger
945 than physical RAM. If a limit of 0 is specified (not using -m), the
946 container's memory is not limited. The actual limit may be rounded up
947 to a multiple of the operating system's page size (the value is very
948 large, that's millions of trillions).
949 This option is not supported on cgroups V1 rootless systems.
952 --memory-reservation=number[unit]
955 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
956 (mebibytes), or g (gibibytes).
957 After setting memory reservation, when the system detects memory con‐
960 tention or low memory, containers are forced to restrict their consump‐
961 tion to their reservation. So always set the value below --memory, oth‐
962 erwise the hard limit takes precedence. By default, memory reservation
963 is the same as memory limit.
964 This option is not supported on cgroups V1 rootless systems.
967 --memory-swap=number[unit]
970 A limit value equal to memory plus swap. A unit can be b (bytes), k
971 (kibibytes), m (mebibytes), or g (gibibytes).
972 Must be used with the -m (--memory) flag. The argument value must be
975 larger than that of
976 -m (--memory) By default, it is set to double the value of --memory.
977 Set number to -1 to enable unlimited swap.
980 This option is not supported on cgroups V1 rootless systems.
983 --memory-swappiness=number
986 Tune a container's memory swappiness behavior. Accepts an integer be‐
987 tween 0 and 100.
988 This flag is only supported on cgroups V1 rootful systems.
991 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
994 Attach a filesystem mount to the container
995 Current supported mount TYPEs are bind, devpts, glob, image, ramfs,
998 tmpfs and volume. [1] ⟨#Footnote1⟩
999 e.g.
1001 type=bind,source=/path/on/host,destination=/path/in/container
1002 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
1004 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
1006 type=devpts,destination=/dev/pts
1008 type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true
1010 type=image,source=fedora,destination=/fedora-image,rw=true
1012 type=ramfs,tmpfs-size=512M,destination=/path/in/container
1014 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
1016 type=tmpfs,destination=/path/in/container,noswap
1018 type=volume,source=vol1,destination=/path/in/container,ro=true
1020 Common Options:
1022 · src, source: mount source spec for bind, glob, and volume. Mandatory for bind and glob.
1024 · dst, destination, target: mount destination spec.
1026 When source globs are specified without the destination directory,
1028 the files and directories are mounted with their complete path
1029 within the container. When the destination is specified, the
1030 files and directories matching the glob on the base file name
1031 on the destination directory are mounted. The option
1032 `type=glob,src=/foo*,destination=/tmp/bar` tells container engines
1033 to mount host files matching /foo* to the /tmp/bar/
1034 directory in the container.
1035 Options specific to volume:
1037 · ro, readonly: true or false (default).
1039 . 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.
1041 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1043 The idmap option supports a custom mapping that can be different than the user namespace used by the container.
1044 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
1045 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.
1046 Multiple ranges are separated with #. If the specified mapping is prepended with a '@' then the mapping is considered relative to the container
1047 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.
1048 Options specific to image:
1050 · rw, readwrite: true or false (default).
1052 Options specific to bind and glob:
1054 · ro, readonly: true or false (default).
1056 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
1058 . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
1060 . relabel: shared, private.
1062 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1064 . 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.
1066 Options specific to tmpfs and ramfs:
1068 · ro, readonly: true or false (default).
1070 · tmpfs-size: Size of the tmpfs/ramfs mount in bytes. Unlimited by default in Linux.
1072 · tmpfs-mode: File mode of the tmpfs/ramfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1074 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default.
1076 · notmpcopyup: Disable copying files from the image to the tmpfs/ramfs.
1078 . 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.
1080 Options specific to devpts:
1082 · uid: UID of the file owner (default 0).
1084 · gid: GID of the file owner (default 0).
1086 · mode: permission mask for the file (default 600).
1088 · max: maximum number of PTYs (default 1048576).
1090 --name=name
1094 Assign a name to the container.
1095 The operator can identify a container in three ways:
1098 • UUID long identifier
1101 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1102 • UUID short identifier (“f78375b1c487”);
1104 • Name (“jonah”).
1106 Podman generates a UUID for each container, and if a name is not as‐
1110 signed to the container with --name then it generates a random string
1111 name. The name can be useful as a more human-friendly way to identify
1112 containers. This works for both background and foreground containers.
1113 --network=mode, --net
1116 Set the network mode for the container.
1117 Valid mode values are:
1120 • bridge[:OPTIONS,...]: Create a network stack on the default
1123 bridge. This is the default for rootful containers. It is pos‐
1124 sible to specify these additional options:
1125 • alias=name: Add network-scoped alias for the container.
1127 • ip=IPv4: Specify a static ipv4 address for this container.
1129 • ip=IPv6: Specify a static ipv6 address for this container.
1131 • mac=MAC: Specify a static mac address for this container.
1133 • interface_name: Specify a name for the created network in‐
1135 terface inside the container.
1136 For example to set a static ipv4 address and a static mac ad‐
1138 dress, use --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.
1139 • <network name or ID>[:OPTIONS,...]: Connect to a user-defined
1141 network; this is the network name or ID from a network created
1142 by podman network create. Using the network name implies the
1143 bridge network mode. It is possible to specify the same op‐
1144 tions described under the bridge mode above. Use the --network
1145 option multiple times to specify additional networks. For
1146 backwards compatibility it is also possible to specify net‐
1147 works comma separated on the first --network argument, however
1148 this prevents you from using the options described under the
1149 bridge section above.
1150 • none: Create a network namespace for the container but do not
1152 configure network interfaces for it, thus the container has no
1153 network connectivity.
1154 • container:id: Reuse another container's network stack.
1156 • host: Do not create a network namespace, the container uses
1158 the host's network. Note: The host mode gives the container
1159 full access to local system services such as D-bus and is
1160 therefore considered insecure.
1161 • ns:path: Path to a network namespace to join.
1163 • private: Create a new namespace for the container. This uses
1165 the bridge mode for rootful containers and slirp4netns for
1166 rootless ones.
1167 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
1169 network stack. This is the default for rootless containers. It
1170 is possible to specify these additional options, they can also
1171 be set with network_cmd_options in containers.conf:
1172 • allow_host_loopback=true|false: Allow slirp4netns to reach
1174 the host loopback IP (default is 10.0.2.2 or the second IP
1175 from slirp4netns cidr subnet when changed, see the cidr op‐
1176 tion below). The default is false.
1177 • mtu=MTU: Specify the MTU to use for this network. (Default
1179 is 65520).
1180 • cidr=CIDR: Specify ip range to use for this network. (De‐
1182 fault is 10.0.2.0/24).
1183 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
1185 quired for outbound_addr6).
1186 • outbound_addr=INTERFACE: Specify the outbound interface
1188 slirp binds to (ipv4 traffic only).
1189 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
1191 binds to.
1192 • outbound_addr6=INTERFACE: Specify the outbound interface
1194 slirp binds to (ipv6 traffic only).
1195 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
1197 binds to.
1198 • port_handler=rootlesskit: Use rootlesskit for port forward‐
1200 ing. Default. Note: Rootlesskit changes the source IP ad‐
1201 dress of incoming packets to an IP address in the container
1202 network namespace, usually 10.0.2.100. If the application
1203 requires the real source IP address, e.g. web server logs,
1204 use the slirp4netns port handler. The rootlesskit port han‐
1205 dler is also used for rootless containers when connected to
1206 user-defined networks.
1207 • port_handler=slirp4netns: Use the slirp4netns port forward‐
1209 ing, it is slower than rootlesskit but preserves the correct
1210 source IP address. This port handler cannot be used for
1211 user-defined networks.
1212 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
1216 working stack.
1217 This is only supported in rootless mode.
1218 By default, IPv4 and IPv6 addresses and routes, as well as the
1219 pod interface name, are copied from the host. If port forward‐
1220 ing isn't configured, ports are forwarded dynamically as ser‐
1221 vices are bound on either side (init namespace or container
1222 namespace). Port forwarding preserves the original source IP
1223 address. Options described in pasta(1) can be specified as
1224 comma-separated arguments.
1225 In terms of pasta(1) options, --config-net is given by de‐
1226 fault, in order to configure networking when the container is
1227 started, and --no-map-gw is also assumed by default, to avoid
1228 direct access from container to host using the gateway ad‐
1229 dress. The latter can be overridden by passing --map-gw in the
1230 pasta-specific options (despite not being an actual pasta(1)
1231 option).
1232 Also, -t none and -u none are passed if, respectively, no TCP
1233 or UDP port forwarding from host to container is configured,
1234 to disable automatic port forwarding based on bound ports.
1235 Similarly, -T none and -U none are given to disable the same
1236 functionality from container to host.
1237 Some examples:
1238 • pasta:--map-gw: Allow the container to directly reach the
1240 host using the gateway address.
1241 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
1243 terface in the container.
1244 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
1246 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
1247 alent to default slirp4netns(1) options: disable IPv6, as‐
1248 sign 10.0.2.0/24 to the tap0 interface in the container,
1249 with gateway 10.0.2.3, enable DNS forwarder reachable at
1250 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
1251 DHCP support.
1252 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
1254 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
1255 to default slirp4netns(1) options with Podman overrides:
1256 same as above, but leave the MTU to 65520 bytes
1257 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
1259 forwarding based on observed bound ports from both host and
1260 container sides
1261 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
1263 tainer to host, using the loopback interface instead of the
1264 tap interface for improved performance
1265 NOTE: For backward compatibility reasons, if there is an exist‐
1267 ing network named pasta, Podman uses it instead of the pasta
1268 mode."?
1269 Invalid if using --dns, --dns-option, or --dns-search with --network
1273 set to none or container:id.
1274 If used together with --pod, the container does not join the pod's net‐
1277 work namespace.
1278 --network-alias=alias
1281 Add a network-scoped alias for the container, setting the alias for all
1282 networks that the container joins. To set a name only for a specific
1283 network, use the alias option as described under the --network option.
1284 If the network has DNS enabled (podman network inspect -f {{.DNSEn‐
1285 abled}} <name>), these aliases can be used for name resolution on the
1286 given network. This option can be specified multiple times. NOTE: When
1287 using CNI a container only has access to aliases on the first network
1288 that it joins. This limitation does not exist with netavark/aardvark-
1289 dns.
1290 --no-healthcheck
1293 Disable any defined healthchecks for container.
1294 --no-hosts
1297 Do not create /etc/hosts for the container. By default, Podman manages
1298 /etc/hosts, adding the container's own IP address and any hosts from
1299 --add-host. --no-hosts disables this, and the image's /etc/hosts is
1300 preserved unmodified.
1301 This option conflicts with --add-host.
1304 --oom-kill-disable
1307 Whether to disable OOM Killer for the container or not.
1308 This flag is not supported on cgroups V2 systems.
1311 --oom-score-adj=num
1314 Tune the host's OOM preferences for containers (accepts values from
1315 -1000 to 1000).
1316 When running in rootless mode, the specified value can't be lower than
1319 the oom_score_adj for the current process. In this case, the oom-score-
1320 adj is clamped to the current process value.
1321 --os=OS
1324 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1325 ample, windows. Unless overridden, subsequent lookups of the same im‐
1326 age in the local storage matches this OS, regardless of the host.
1327 --passwd-entry=ENTRY
1330 Customize the entry that is written to the /etc/passwd file within the
1331 container when --passwd is used.
1332 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1335 placed with their value at runtime.
1336 --personality=persona
1339 Personality sets the execution domain via Linux personality(2).
1340 --pid=mode
1343 Set the PID namespace mode for the container. The default is to create
1344 a private PID namespace for the container.
1345 • container:id: join another container's PID namespace;
1348 • host: use the host's PID namespace for the container. Note the
1350 host mode gives the container full access to local PID and is
1351 therefore considered insecure;
1352 • ns:path: join the specified PID namespace;
1354 • private: create a new namespace for the container (default).
1356 --pidfile=path
1360 When the pidfile location is specified, the container process' PID is
1361 written to the pidfile. (This option is not available with the remote
1362 Podman client, including Mac and Windows (excluding WSL2) machines) If
1363 the pidfile option is not specified, the container process' PID is
1364 written to /run/containers/storage/${storage-driver}-contain‐
1365 ers/$CID/userdata/pidfile.
1366 After the container is started, the location for the pidfile can be
1369 discovered with the following podman inspect command:
1370 $ podman inspect --format '{{ .PidFile }}' $CID
1372 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1373 --pids-limit=limit
1377 Tune the container's pids limit. Set to -1 to have unlimited pids for
1378 the container. The default is 2048 on systems that support "pids"
1379 cgroup controller.
1380 --platform=OS/ARCH
1383 Specify the platform for selecting the image. (Conflicts with --arch
1384 and --os) The --platform option can be used to override the current ar‐
1385 chitecture and operating system. Unless overridden, subsequent lookups
1386 of the same image in the local storage matches this platform, regard‐
1387 less of the host.
1388 --pod=name
1391 Run container in an existing pod. Podman makes the pod automatically if
1392 the pod name is prefixed with new:. To make a pod with more granular
1393 options, use the podman pod create command before creating a container.
1394 When a container is run with a pod with an infra-container, the infra-
1395 container is started first.
1396 --pod-id-file=file
1399 Run container in an existing pod and read the pod's ID from the speci‐
1400 fied file. When a container is run within a pod which has an infra-
1401 container, the infra-container starts first.
1402 --privileged
1405 Give extended privileges to this container. The default is false.
1406 By default, Podman containers are unprivileged (=false) and cannot, for
1409 example, modify parts of the operating system. This is because by de‐
1410 fault a container is only allowed limited access to devices. A "privi‐
1411 leged" container is given the same access to devices as the user
1412 launching the container, with the exception of virtual consoles
1413 (/dev/tty\d+) when running in systemd mode (--systemd=always).
1414 A privileged container turns off the security features that isolate the
1417 container from the host. Dropped Capabilities, limited devices, read-
1418 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1419 all disabled. Due to the disabled security features, the privileged
1420 field should almost never be set as containers can easily break out of
1421 confinement.
1422 Containers running in a user namespace (e.g., rootless containers) can‐
1425 not have more privileges than the user that launched them.
1426 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1429 Publish a container's port, or range of ports, to the host.
1430 Both hostPort and containerPort can be specified as a range of ports.
1433 When specifying ranges for both, the number of container ports in the
1434 range must match the number of host ports in the range.
1435 If host IP is set to 0.0.0.0 or not set at all, the port is bound on
1438 all IPs on the host.
1439 By default, Podman publishes TCP ports. To publish a UDP port instead,
1442 give udp as protocol. To publish both TCP and UDP ports, set --publish
1443 twice, with tcp, and udp as protocols respectively. Rootful containers
1444 can also publish ports using the sctp protocol.
1445 Host port does not have to be specified (e.g. podman run -p
1448 127.0.0.1::80). If it is not, the container port is randomly assigned
1449 a port on the host.
1450 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1453 TAINERPORT.
1454 Note that the network drivers macvlan and ipvlan do not support port
1457 forwarding, it will have no effect on these networks.
1458 Note: If a container runs within a pod, it is not necessary to publish
1461 the port for the containers in the pod. The port must only be published
1462 by the pod itself. Pod network stacks act like the network stack on the
1463 host - when there are a variety of containers in the pod, and programs
1464 in the container, all sharing a single interface and IP address, and
1465 associated ports. If one container binds to a port, no other container
1466 can use that port within the pod while it is in use. Containers in the
1467 pod can also communicate over localhost by having one container bind to
1468 localhost in the pod, and another connect to that port.
1469 --publish-all, -P
1472 Publish all exposed ports to random ports on the host interfaces. The
1473 default is false.
1474 When set to true, publish all exposed ports to the host interfaces. If
1477 the operator uses -P (or -p) then Podman makes the exposed port acces‐
1478 sible on the host and the ports are available to any client that can
1479 reach the host.
1480 When using this option, Podman binds any exposed port to a random port
1483 on the host within an ephemeral port range defined by
1484 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1485 the host ports and the exposed ports, use podman port.
1486 --pull=policy
1489 Pull image policy. The default is missing.
1490 • always: Always pull the image and throw an error if the pull
1493 fails.
1494 • missing: Pull the image only when the image is not in the lo‐
1496 cal containers storage. Throw an error if no image is found
1497 and the pull fails.
1498 • never: Never pull the image but use the one from the local
1500 containers storage. Throw an error if no image is found.
1501 • newer: Pull if the image on the registry is newer than the one
1503 in the local containers storage. An image is considered to be
1504 newer when the digests are different. Comparing the time
1505 stamps is prone to errors. Pull errors are suppressed if a
1506 local image was found.
1507 --quiet, -q
1511 Suppress output information when pulling images
1512 --rdt-class=intel-rdt-class-of-service
1515 Rdt-class sets the class of service (CLOS or COS) for the container to
1516 run in. Based on the Cache Allocation Technology (CAT) feature that is
1517 part of Intel's Resource Director Technology (RDT) feature set, all
1518 container processes will run within the pre-configured COS, represent‐
1519 ing a part of the cache. The COS has to be created and configured using
1520 a pseudo file system (usually mounted at /sys/fs/resctrl) that the
1521 resctrl kernel driver provides. Assigning the container to a COS re‐
1522 quires root privileges and thus doesn't work in a rootless environment.
1523 Currently, the feature is only supported using runc as a runtime. See
1524 ⟨https://docs.kernel.org/arch/x86/resctrl.html⟩ for more details on
1525 creating a COS before a container can be assigned to it.
1526 --read-only
1529 Mount the container's root filesystem as read-only.
1530 By default, container root filesystems are writable, allowing processes
1533 to write files anywhere. By specifying the --read-only flag, the con‐
1534 tainers root filesystem are mounted read-only prohibiting any writes.
1535 --read-only-tmpfs
1538 When running --read-only containers, mount a read-write tmpfs on /dev,
1539 /dev/shm, /run, /tmp, and /var/tmp. The default is true.
1540 ┌────────────┬───────────────────┬─────┬──────────────────────┐
1543 │--read-only │ --read-only-tmpfs │ / │ /run, /tmp, /var/tmp │
1544 ├────────────┼───────────────────┼─────┼──────────────────────┤
1545 │true │ true │ r/o │ r/w │
1546 ├────────────┼───────────────────┼─────┼──────────────────────┤
1547 │true │ false │ r/o │ r/o │
1548 ├────────────┼───────────────────┼─────┼──────────────────────┤
1549 │false │ false │ r/w │ r/w │
1550 ├────────────┼───────────────────┼─────┼──────────────────────┤
1551 │false │ true │ r/w │ r/w │
1552 └────────────┴───────────────────┴─────┴──────────────────────┘
1553 When --read-only=true and --read-only-tmpfs=true additional tmpfs are
1555 mounted on the /tmp, /run, and /var/tmp directories.
1556 When --read-only=true and --read-only-tmpfs=false /dev and /dev/shm are
1559 marked Read/Only and no tmpfs are mounted on /tmp, /run and /var/tmp.
1560 The directories are exposed from the underlying image, meaning they are
1561 read-only by default. This makes the container totally read-only. No
1562 writable directories exist within the container. In this mode writable
1563 directories need to be added via external volumes or mounts.
1564 By default, when --read-only=false, the /dev and /dev/shm are
1567 read/write, and the /tmp, /run, and /var/tmp are read/write directories
1568 from the container image.
1569 --replace
1572 If another container with the same name already exists, replace and re‐
1573 move it. The default is false.
1574 --requires=container
1577 Specify one or more requirements. A requirement is a dependency con‐
1578 tainer that is started before this container. Containers can be speci‐
1579 fied by name or ID, with multiple containers being separated by commas.
1580 --restart=policy
1583 Restart policy to follow when containers exit. Restart policy does not
1584 take effect if a container is stopped via the podman kill or podman
1585 stop commands.
1586 Valid policy values are:
1589 • no : Do not restart containers on exit
1592 • never : Synonym for no; do not restart con‐
1594 tainers on exit
1595 • on-failure[:max_retries] : Restart containers when they exit
1597 with a non-zero exit code, retrying indefinitely or until the
1598 optional max_retries count is hit
1599 • always : Restart containers when they exit,
1601 regardless of status, retrying indefinitely
1602 • unless-stopped : Identical to always
1604 Podman provides a systemd unit file, podman-restart.service, which
1608 restarts containers after a system reboot.
1609 When running containers in systemd services, use the restart function‐
1612 ality provided by systemd. In other words, do not use this option in a
1613 container unit, instead set the Restart= systemd directive in the [Ser‐
1614 vice] section. See podman-systemd.unit(5) and systemd.service(5).
1615 --rm
1618 Automatically remove the container and any anonymous unnamed volume as‐
1619 sociated with the container when it exits. The default is false.
1620 --rootfs
1623 If specified, the first argument refers to an exploded container on the
1624 file system.
1625 This is useful to run a container without requiring any image manage‐
1628 ment, the rootfs of the container is assumed to be managed externally.
1629 Overlay Rootfs Mounts
1632 The :O flag tells Podman to mount the directory from the rootfs path as
1635 storage using the overlay file system. The container processes can mod‐
1636 ify content within the mount point which is stored in the container
1637 storage in a separate directory. In overlay terms, the source directory
1638 is the lower, and the container storage directory is the upper. Modifi‐
1639 cations to the mount point are destroyed when the container finishes
1640 executing, similar to a tmpfs mount point being unmounted.
1641 Note: On SELinux systems, the rootfs needs the correct label, which is
1644 by default unconfined_u:object_r:container_file_t:s0.
1645 idmap
1648 If idmap is specified, create an idmapped mount to the target user
1651 namespace in the container. The idmap option supports a custom mapping
1652 that can be different than the user namespace used by the container.
1653 The mapping can be specified after the idmap option like:
1654 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
1655 value is the start of the backing file system IDs that are mapped to
1656 the second value on the host. The length of this mapping is given in
1657 the third value. Multiple ranges are separated with #.
1658 --sdnotify=container | conmon | healthy | ignore
1661 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1662 Type=notify.
1663 Default is container, which means allow the OCI runtime to proxy the
1666 socket into the container to receive ready notification. Podman sets
1667 the MAINPID to conmon's pid. The conmon option sets MAINPID to con‐
1668 mon's pid, and sends READY when the container has started. The socket
1669 is never passed to the runtime or the container. The healthy option
1670 sets MAINPID to conmon's pid, and sends READY when the container has
1671 turned healthy; requires a healthcheck to be set. The socket is never
1672 passed to the runtime or the container. The ignore option removes NO‐
1673 TIFY_SOCKET from the environment for itself and child processes, for
1674 the case where some other process above Podman uses NOTIFY_SOCKET and
1675 Podman does not use it.
1676 --seccomp-policy=policy
1679 Specify the policy to select the seccomp profile. If set to image, Pod‐
1680 man looks for a "io.containers.seccomp.profile" label in the container-
1681 image config and use its value as a seccomp profile. Otherwise, Podman
1682 follows the default policy by applying the default profile unless spec‐
1683 ified otherwise via --security-opt seccomp as described below.
1684 Note that this feature is experimental and may change in the future.
1687 --secret=secret[,opt=opt ...]
1690 Give the container access to a secret. Can be specified multiple times.
1691 A secret is a blob of sensitive data which a container needs at runtime
1694 but is not stored in the image or in source control, such as usernames
1695 and passwords, TLS certificates and keys, SSH keys or other important
1696 generic strings or binary content (up to 500 kb in size).
1697 When secrets are specified as type mount, the secrets are copied and
1700 mounted into the container when a container is created. When secrets
1701 are specified as type env, the secret is set as an environment variable
1702 within the container. Secrets are written in the container at the time
1703 of container creation, and modifying the secret using podman secret
1704 commands after the container is created affects the secret inside the
1705 container.
1706 Secrets and its storage are managed using the podman secret command.
1709 Secret Options
1712 • type=mount|env : How the secret is exposed to the con‐
1715 tainer.
1716 mount mounts the secret into the container
1717 as a file.
1718 env exposes the secret as an environment
1719 variable.
1720 Defaults to mount.
1721 • target=target : Target of secret.
1723 For mounted secrets, this is the path to
1724 the secret inside the container.
1725 If a fully qualified path is provided, the
1726 secret is mounted at that location.
1727 Otherwise, the secret is mounted to
1728 /run/secrets/target for linux containers
1729 or
1730 /var/run/secrets/target for freebsd con‐
1731 tainers.
1732 If the target is not set, the secret is
1733 mounted to /run/secrets/secretname by default.
1734 For env secrets, this is the environment
1735 variable key. Defaults to secretname.
1736 • uid=0 : UID of secret. Defaults to 0. Mount secret
1738 type only.
1739 • gid=0 : GID of secret. Defaults to 0. Mount secret
1741 type only.
1742 • mode=0 : Mode of secret. Defaults to 0444. Mount
1744 secret type only.
1745 Examples
1749 Mount at /my/location/mysecret with UID 1:
1752 --secret mysecret,target=/my/location/mysecret,uid=1
1754 Mount at /run/secrets/customtarget with mode 0777:
1758 --secret mysecret,target=customtarget,mode=0777
1760 Create a secret environment variable called ENVSEC:
1764 --secret mysecret,type=env,target=ENVSEC
1766 --security-opt=option
1770 Security Options
1771 • apparmor=unconfined : Turn off apparmor confinement for the
1774 container
1775 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1777 file for the container
1778 • label=user:USER: Set the label user for the container pro‐
1780 cesses
1781 • label=role:ROLE: Set the label role for the container pro‐
1783 cesses
1784 • label=type:TYPE: Set the label process type for the container
1786 processes
1787 • label=level:LEVEL: Set the label level for the container pro‐
1789 cesses
1790 • label=filetype:TYPE: Set the label file type for the container
1792 files
1793 • label=disable: Turn off label separation for the container
1795 Note: Labeling can be disabled for all containers by setting la‐
1799 bel=false in the containers.conf (/etc/containers/containers.conf or
1800 $HOME/.config/containers/containers.conf) file.
1801 • label=nested: Allows SELinux modifications within the con‐
1804 tainer. Containers are allowed to modify SELinux labels on
1805 files and processes, as long as SELinux policy allows. Without
1806 nested, containers view SELinux as disabled, even when it is
1807 enabled on the host. Containers are prevented from setting any
1808 labels.
1809 • mask=/path/1:/path/2: The paths to mask separated by a colon.
1811 A masked path cannot be accessed inside the container.
1812 • no-new-privileges: Disable container processes from gaining
1814 additional privileges.
1815 • seccomp=unconfined: Turn off seccomp confinement for the con‐
1817 tainer.
1818 • seccomp=profile.json: JSON file to be used as a seccomp fil‐
1820 ter. Note that the io.podman.annotations.seccomp annotation is
1821 set with the specified value as shown in podman inspect.
1822 • proc-opts=OPTIONS : Comma-separated list of options to use for
1824 the /proc mount. More details for the possible mount options
1825 are specified in the proc(5) man page.
1826 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1828 (/proc/*): Paths to unmask separated by a colon. If set to
1829 ALL, it unmasks all the paths that are masked or made read-
1830 only by default. The default masked paths are /proc/acpi,
1831 /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_de‐
1832 bug, /proc/scsi, /proc/timer_list, /proc/timer_stats,
1833 /sys/firmware, and /sys/fs/selinux, /sys/devices/virtual/pow‐
1834 ercap. The default paths that are read-only are /proc/asound,
1835 /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trig‐
1836 ger, /sys/fs/cgroup.
1837 Note: Labeling can be disabled for all containers by setting la‐
1841 bel=false in the containers.conf(5) file.
1842 --shm-size=number[unit]
1845 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1846 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1847 bytes. If the size is omitted, the default is 64m. When size is 0,
1848 there is no limit on the amount of memory used for IPC by the con‐
1849 tainer. This option conflicts with --ipc=host.
1850 --shm-size-systemd=number[unit]
1853 Size of systemd-specific tmpfs mounts such as /run, /run/lock,
1854 /var/log/journal and /tmp. A unit can be b (bytes), k (kibibytes), m
1855 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1856 bytes. If the size is omitted, the default is 64m. When size is 0, the
1857 usage is limited to 50% of the host's available memory.
1858 --stop-signal=signal
1861 Signal to stop a container. Default is SIGTERM.
1862 --stop-timeout=seconds
1865 Timeout to stop a container. Default is 10. Remote connections use lo‐
1866 cal containers.conf for defaults.
1867 --subgidname=name
1870 Run the container in a new user namespace using the map with name in
1871 the /etc/subgid file. If running rootless, the user needs to have the
1872 right to use the mapping. See subgid(5). This flag conflicts with
1873 --userns and --gidmap.
1874 --subuidname=name
1877 Run the container in a new user namespace using the map with name in
1878 the /etc/subuid file. If running rootless, the user needs to have the
1879 right to use the mapping. See subuid(5). This flag conflicts with
1880 --userns and --uidmap.
1881 --sysctl=name=value
1884 Configure namespaced kernel parameters at runtime.
1885 For the IPC namespace, the following sysctls are allowed:
1888 • kernel.msgmax
1891 • kernel.msgmnb
1893 • kernel.msgmni
1895 • kernel.sem
1897 • kernel.shmall
1899 • kernel.shmmax
1901 • kernel.shmmni
1903 • kernel.shm_rmid_forced
1905 • Sysctls beginning with fs.mqueue.*
1907 Note: if using the --ipc=host option, the above sysctls are not al‐
1911 lowed.
1912 For the network namespace, only sysctls beginning with net.* are al‐
1915 lowed.
1916 Note: if using the --network=host option, the above sysctls are not al‐
1919 lowed.
1920 --systemd=true | false | always
1923 Run container in systemd mode. The default is true.
1924 • true enables systemd mode only when the command executed in‐
1927 side the container is systemd, /usr/sbin/init, /sbin/init or
1928 /usr/local/sbin/init.
1929 • false disables systemd mode.
1931 • always enforces the systemd mode to be enabled.
1933 Running the container in systemd mode causes the following changes:
1937 • Podman mounts tmpfs file systems on the following directories
1940 • /run
1942 • /run/lock
1944 • /tmp
1946 • /sys/fs/cgroup/systemd (on a cgroup v1 system)
1948 • /var/lib/journal
1950 • Podman sets the default stop signal to SIGRTMIN+3.
1954 • Podman sets container_uuid environment variable in the con‐
1956 tainer to the first 32 characters of the container ID.
1957 • Podman does not mount virtual consoles (/dev/tty\d+) when run‐
1959 ning with --privileged.
1960 • On cgroup v2, /sys/fs/cgroup is mounted writeable.
1962 This allows systemd to run in a confined container without any modifi‐
1966 cations.
1967 Note that on SELinux systems, systemd attempts to write to the cgroup
1970 file system. Containers writing to the cgroup file system are denied by
1971 default. The container_manage_cgroup boolean must be enabled for this
1972 to be allowed on an SELinux separated system.
1973 setsebool -P container_manage_cgroup true
1975 --timeout=seconds
1979 Maximum time a container is allowed to run before conmon sends it the
1980 kill signal. By default containers run until they exit or are stopped
1981 by podman stop.
1982 --tls-verify
1985 Require HTTPS and verify certificates when contacting registries (de‐
1986 fault: true). If explicitly set to true, TLS verification is used. If
1987 set to false, TLS verification is not used. If not specified, TLS ver‐
1988 ification is used unless the target registry is listed as an insecure
1989 registry in containers-registries.conf(5)
1990 --tmpfs=fs
1993 Create a tmpfs mount.
1994 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1997 ple:
1998 $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
2000 This command mounts a tmpfs at /tmp within the container. The supported
2004 mount options are the same as the Linux default mount flags. If no op‐
2005 tions are specified, the system uses the following options:
2006 rw,noexec,nosuid,nodev.
2007 --tty, -t
2010 Allocate a pseudo-TTY. The default is false.
2011 When set to true, Podman allocates a pseudo-tty and attach to the stan‐
2014 dard input of the container. This can be used, for example, to run a
2015 throwaway interactive shell.
2016 NOTE: The --tty flag prevents redirection of standard output. It com‐
2019 bines STDOUT and STDERR, it can insert control characters, and it can
2020 hang pipes. This option is only used when run interactively in a termi‐
2021 nal. When feeding input to Podman, use -i only, not -it.
2022 --tz=timezone
2025 Set timezone in container. This flag takes area-based timezones, GMT
2026 time, as well as local, which sets the timezone in the container to
2027 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
2028 Remote connections use local containers.conf for defaults
2029 --uidmap=[flags]container_uid:from_uid[:amount]
2032 Run the container in a new user namespace using the supplied UID map‐
2033 ping. This option conflicts with the --userns and --subuidname options.
2034 This option provides a way to map host UIDs to container UIDs. It can
2035 be passed several times to map different ranges.
2036 The possible values of the optional flags are discussed further down on
2039 this page. The amount value is optional and assumed to be 1 if not
2040 given.
2041 The from_uid value is based upon the user running the command, either
2044 rootful or rootless users.
2045 • rootful user: [flags]container_uid:host_uid[:amount]
2048 • rootless user: [flags]container_uid:intermediate_uid[:amount]
2050 Rootful mappings
2054 When podman create is called by a privileged user, the option --uidmap
2057 works as a direct mapping between host UIDs and container UIDs.
2058 host UID -> container UID
2061 The amount specifies the number of consecutive UIDs that is mapped. If
2064 for example amount is 4 the mapping looks like:
2065 ┌─────────────┬───────────────────┐
2068 │host UID │ container UID │
2069 ├─────────────┼───────────────────┤
2070 │from_uid │ container_uid │
2071 ├─────────────┼───────────────────┤
2072 │from_uid + 1 │ container_uid + 1 │
2073 ├─────────────┼───────────────────┤
2074 │from_uid + 2 │ container_uid + 2 │
2075 ├─────────────┼───────────────────┤
2076 │from_uid + 3 │ container_uid + 3 │
2077 └─────────────┴───────────────────┘
2078 Rootless mappings
2080 When podman create is called by an unprivileged user (i.e. running
2083 rootless), the value from_uid is interpreted as an "intermediate UID".
2084 In the rootless case, host UIDs are not mapped directly to container
2085 UIDs. Instead the mapping happens over two mapping steps:
2086 host UID -> intermediate UID -> container UID
2089 The --uidmap option only influences the second mapping step.
2092 The first mapping step is derived by Podman from the contents of the
2095 file /etc/subuid and the UID of the user calling Podman.
2096 First mapping step:
2099 ┌────────────────────┬──────────────────┐
2102 │host UID │ intermediate UID │
2103 ├────────────────────┼──────────────────┤
2104 │UID for Podman user │ 0 │
2105 ├────────────────────┼──────────────────┤
2106 │1st subordinate UID │ 1 │
2107 ├────────────────────┼──────────────────┤
2108 │2nd subordinate UID │ 2 │
2109 ├────────────────────┼──────────────────┤
2110 │3rd subordinate UID │ 3 │
2111 ├────────────────────┼──────────────────┤
2112 │nth subordinate UID │ n │
2113 └────────────────────┴──────────────────┘
2114 To be able to use intermediate UIDs greater than zero, the user needs
2116 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
2117 The second mapping step is configured with --uidmap.
2120 If for example amount is 5 the second mapping step looks like:
2123 ┌─────────────────┬───────────────────┐
2126 │intermediate UID │ container UID │
2127 ├─────────────────┼───────────────────┤
2128 │from_uid │ container_uid │
2129 ├─────────────────┼───────────────────┤
2130 │from_uid + 1 │ container_uid + 1 │
2131 ├─────────────────┼───────────────────┤
2132 │from_uid + 2 │ container_uid + 2 │
2133 ├─────────────────┼───────────────────┤
2134 │from_uid + 3 │ container_uid + 3 │
2135 ├─────────────────┼───────────────────┤
2136 │from_uid + 4 │ container_uid + 4 │
2137 └─────────────────┴───────────────────┘
2138 When running as rootless, Podman uses all the ranges configured in the
2140 /etc/subuid file.
2141 The current user ID is mapped to UID=0 in the rootless user namespace.
2144 Every additional range is added sequentially afterward:
2145 ┌──────────────────────┬─────────────────────────┬──────────────────────┐
2148 │host │ rootless user namespace │ length │
2149 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2150 │$UID │ 0 │ 1 │
2151 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2152 │1 │ $FIRST_RANGE_ID │ $FIRST_RANGE_LENGTH │
2153 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2154 │1+$FIRST_RANGE_LENGTH │ $SECOND_RANGE_ID │ $SECOND_RANGE_LENGTH │
2155 └──────────────────────┴─────────────────────────┴──────────────────────┘
2156 Referencing a host ID from the parent namespace
2158 As a rootless user, the given host ID in --uidmap or --gidmap is mapped
2161 from the intermediate namespace generated by Podman. Sometimes it is
2162 desirable to refer directly at the host namespace. It is possible to
2163 manually do so, by running podman unshare cat /proc/self/gid_map, find‐
2164 ing the desired host id at the second column of the output, and getting
2165 the corresponding intermediate id from the first column.
2166 Podman can perform all that by preceding the host id in the mapping
2169 with the @ symbol. For instance, by specifying --gidmap 100000:@2000:1,
2170 podman will look up the intermediate id corresponding to host id 2000
2171 and it will map the found intermediate id to the container id 100000.
2172 The given host id must have been subordinated (otherwise it would not
2173 be mapped into the intermediate space in the first place).
2174 If the length is greater than one, for instance with --gidmap
2177 100000:@2000:2, Podman will map host ids 2000 and 2001 to 100000 and
2178 100001, respectively, regardless of how the intermediate mapping is de‐
2179 fined.
2180 Extending previous mappings
2183 Some mapping modifications may be cumbersome. For instance, a user
2186 starts with a mapping such as --gidmap="0:0:65000", that needs to be
2187 changed such as the parent id 1000 is mapped to container id 100000 in‐
2188 stead, leaving container id 1 unassigned. The corresponding --gidmap
2189 becomes --gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1".
2190 This notation can be simplified using the + flag, that takes care of
2193 breaking previous mappings removing any conflicting assignment with the
2194 given mapping. The flag is given before the container id as follows:
2195 --gidmap="0:0:65000" --gidmap="+100000:1:1"
2196 ┌─────┬─────────────┬─────────────────────────────┐
2199 │Flag │ Example │ Description │
2200 ├─────┼─────────────┼─────────────────────────────┤
2201 │+ │ +100000:1:1 │ Extend the previous mapping │
2202 └─────┴─────────────┴─────────────────────────────┘
2203 This notation leads to gaps in the assignment, so it may be convenient
2205 to fill those gaps afterwards: --gidmap="0:0:65000"
2206 --gidmap="+100000:1:1" --gidmap="1:65001:1"
2207 One specific use case for this flag is in the context of rootless
2210 users. A rootless user may specify mappings with the + flag as in
2211 --gidmap="+100000:1:1". Podman will then "fill the gaps" starting from
2212 zero with all the remaining intermediate ids. This is convenient when a
2213 user wants to map a specific intermediate id to a container id, leaving
2214 the rest of subordinate ids to be mapped by Podman at will.
2215 Passing only one of --uidmap or --gidmap
2218 Usually, subordinated user and group ids are assigned simultaneously,
2221 and for any user the subordinated user ids match the subordinated group
2222 ids. For convenience, if only one of --uidmap or --gidmap is given,
2223 podman assumes the mapping refers to both UIDs and GIDs and applies the
2224 given mapping to both. If only one value of the two needs to be
2225 changed, the mappings should include the u or the g flags to specify
2226 that they only apply to UIDs or GIDs and should not be copied over.
2227 ┌─────┬───────────────┬─────────────────────┐
2230 │flag │ Example │ Description │
2231 ├─────┼───────────────┼─────────────────────┤
2232 │u │ u20000:2000:1 │ The mapping only │
2233 │ │ │ applies to UIDs │
2234 ├─────┼───────────────┼─────────────────────┤
2235 │g │ g10000:1000:1 │ The mapping only │
2236 │ │ │ applies to GIDs │
2237 └─────┴───────────────┴─────────────────────┘
2238 For instance given the command
2240 podman create --gidmap "0:0:1000" --gidmap "g2000:2000:1"
2242 Since no --uidmap is given, the --gidmap is copied to --uidmap, giving
2246 a command equivalent to
2247 podman create --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"
2249 The --gidmap "g2000:2000:1" used the g flag and therefore it was not
2253 copied to --uidmap.
2254 Rootless mapping of additional host GIDs
2257 A rootless user may desire to map a specific host group that has al‐
2260 ready been subordinated within /etc/subgid without specifying the rest
2261 of the mapping.
2262 This can be done with --gidmap "+gcontainer_gid:@host_gid"
2265 Where:
2268 • The host GID is given through the @ symbol
2271 • The mapping of this GID is not copied over to --usermap thanks
2273 to the g flag.
2274 • The rest of the container IDs will be mapped starting from 0
2276 to n, with all the remaining subordinated GIDs, thanks to the
2277 + flag.
2278 For instance, if a user belongs to the group 2000 and that group is
2282 subordinated to that user (with usermod --add-subgids 2000-2000 $USER),
2283 the user can map the group into the container with:
2284 --gidmap=+g100000:@2000.
2285 If this mapping is combined with the option, --group-add=keep-groups,
2288 the process in the container will belong to group 100000, and files be‐
2289 longing to group 2000 in the host will appear as being owned by group
2290 100000 inside the container.
2291 podman run --group-add=keep-groups --gidmap="+g100000:@2000" ...
2293 No subordinate UIDs
2297 Even if a user does not have any subordinate UIDs in /etc/subuid,
2300 --uidmap can be used to map the normal UID of the user to a container
2301 UID by running podman create --uidmap $container_uid:0:1 --user $con‐
2302 tainer_uid ....
2303 Pods
2306 The --uidmap option cannot be called in conjunction with the --pod op‐
2309 tion as a uidmap cannot be set on the container level when in a pod.
2310 --ulimit=option
2313 Ulimit options. Sets the ulimits values inside of the container.
2314 --ulimit with a soft and hard limit in the format =[:]. For example:
2317 $ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024
2320 Set -1 for the soft or hard limit to set the limit to the maximum limit
2323 of the current process. In rootful mode this is often unlimited.
2324 Use host to copy the current configuration from the host.
2327 Don't use nproc with the ulimit flag as Linux uses nproc to set the
2330 maximum number of processes available to a user, not to a container.
2331 Use the --pids-limit option to modify the cgroup control to limit the
2334 number of processes within a container.
2335 --umask=umask
2338 Set the umask inside the container. Defaults to 0022. Remote connec‐
2339 tions use local containers.conf for defaults
2340 --unsetenv=env
2343 Unset default environment variables for the container. Default environ‐
2344 ment variables include variables provided natively by Podman, environ‐
2345 ment variables configured by the image, and environment variables from
2346 containers.conf.
2347 --unsetenv-all
2350 Unset all default environment variables for the container. Default en‐
2351 vironment variables include variables provided natively by Podman, en‐
2352 vironment variables configured by the image, and environment variables
2353 from containers.conf.
2354 --user, -u=user[:group]
2357 Sets the username or UID used and, optionally, the groupname or GID for
2358 the specified command. Both user and group may be symbolic or numeric.
2359 Without this argument, the command runs as the user specified in the
2362 container image. Unless overridden by a USER command in the Container‐
2363 file or by a value passed to this option, this user generally defaults
2364 to root.
2365 When a user namespace is not in use, the UID and GID used within the
2368 container and on the host match. When user namespaces are in use, how‐
2369 ever, the UID and GID in the container may correspond to another UID
2370 and GID on the host. In rootless containers, for example, a user name‐
2371 space is always used, and root in the container by default corresponds
2372 to the UID and GID of the user invoking Podman.
2373 --userns=mode
2376 Set the user namespace mode for the container.
2377 If --userns is not set, the default value is determined as follows. -
2380 If --pod is set, --userns is ignored and the user namespace of the pod
2381 is used. - If the environment variable PODMAN_USERNS is set its value
2382 is used. - If userns is specified in containers.conf this value is
2383 used. - Otherwise, --userns=host is assumed.
2384 --userns="" (i.e., an empty string) is an alias for --userns=host.
2387 This option is incompatible with --gidmap, --uidmap, --subuidname and
2390 --subgidname.
2391 Rootless user --userns=Key mappings:
2394 ┌────────────────────────┬───────────┬─────────────────────┐
2397 │Key │ Host User │ Container User │
2398 ├────────────────────────┼───────────┼─────────────────────┤
2399 │auto │ $UID │ nil (Host User UID │
2400 │ │ │ is not mapped into │
2401 │ │ │ container.) │
2402 ├────────────────────────┼───────────┼─────────────────────┤
2403 │host │ $UID │ 0 (Default User ac‐ │
2404 │ │ │ count mapped to │
2405 │ │ │ root user in con‐ │
2406 │ │ │ tainer.) │
2407 ├────────────────────────┼───────────┼─────────────────────┤
2408 │keep-id │ $UID │ $UID (Map user ac‐ │
2409 │ │ │ count to same UID │
2410 │ │ │ within container.) │
2411 ├────────────────────────┼───────────┼─────────────────────┤
2412 │keep-id:uid=200,gid=210 │ $UID │ 200:210 (Map user │
2413 │ │ │ account to speci‐ │
2414 │ │ │ fied UID, GID value │
2415 │ │ │ within container.) │
2416 ├────────────────────────┼───────────┼─────────────────────┤
2417 │nomap │ $UID │ nil (Host User UID │
2418 │ │ │ is not mapped into │
2419 │ │ │ container.) │
2420 └────────────────────────┴───────────┴─────────────────────┘
2421 Valid mode values are:
2423 auto[:OPTIONS,...]: automatically create a unique user namespace.
2426 • rootful mode: The --userns=auto flag requires that the user
2429 name containers be specified in the /etc/subuid and /etc/sub‐
2430 gid files, with an unused range of subordinate user IDs that
2431 Podman containers are allowed to allocate.
2432 Example: containers:2147483647:2147483648.
2436 • rootless mode: The users range from the /etc/subuid and
2439 /etc/subgid files will be used. Note running a single con‐
2440 tainer without using --userns=auto will use the entire range
2441 of UIDs and not allow further subdividing. See subuid(5).
2442 Podman allocates unique ranges of UIDs and GIDs from the containers
2446 subordinate user IDs. The size of the ranges is based on the number of
2447 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
2448 den with the size option.
2449 The option --userns=keep-id uses all the subuids and subgids of the
2452 user. The option --userns=nomap uses all the subuids and subgids of
2453 the user except the user's own ID. Using --userns=auto when starting
2454 new containers does not work as long as any containers exist that were
2455 started with --userns=keep-id or --userns=nomap.
2456 Valid auto options:
2459 • gidmapping=CONTAINER_GID:HOST_GID:SIZE: to force a GID mapping
2462 to be present in the user namespace.
2463 • size=SIZE: to specify an explicit size for the automatic user
2465 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
2466 fied, auto estimates a size for the user namespace.
2467 • uidmapping=CONTAINER_UID:HOST_UID:SIZE: to force a UID mapping
2469 to be present in the user namespace.
2470 container:id: join the user namespace of the specified container.
2474 host or "" (empty string): run in the user namespace of the caller. The
2477 processes running in the container have the same privileges on the host
2478 as any other process launched by the calling user.
2479 keep-id: creates a user namespace where the current user's UID:GID are
2482 mapped to the same values in the container. For containers created by
2483 root, the current mapping is created into a new user namespace.
2484 Valid keep-id options:
2487 • uid=UID: override the UID inside the container that is used to
2490 map the current user to.
2491 • gid=GID: override the GID inside the container that is used to
2493 map the current user to.
2494 nomap: creates a user namespace where the current rootless user's
2498 UID:GID are not mapped into the container. This option is not allowed
2499 for containers created by the root user.
2500 ns:namespace: run the container in the given existing user namespace.
2503 --uts=mode
2506 Set the UTS namespace mode for the container. The following values are
2507 supported:
2508 • host: use the host's UTS namespace inside the container.
2511 • private: create a new namespace for the container (default).
2513 • ns:[path]: run the container in the given existing UTS name‐
2515 space.
2516 • container:[container]: join the UTS namespace of the specified
2518 container.
2519 --variant=VARIANT
2523 Use VARIANT instead of the default architecture variant of the con‐
2524 tainer image. Some images can use multiple variants of the arm archi‐
2525 tectures, such as arm/v5 and arm/v7.
2526 --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2529 Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Pod‐
2530 man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2531 man container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR mounts the
2532 named volume from the host into the container. If no such named volume
2533 exists, Podman creates one. If no source is given, the volume is cre‐
2534 ated as an anonymously named volume with a randomly generated name, and
2535 is removed when the container is removed via the --rm flag or the pod‐
2536 man rm --volumes command.
2537 (Note when using the remote client, including Mac and Windows (exclud‐
2540 ing WSL2) machines, the volumes are mounted from the remote server, not
2541 necessarily the client machine.)
2542 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2545 • rw|ro
2548 • z|Z
2550 • [O]
2552 • [U]
2554 • [no]copy
2556 • [no]dev
2558 • [no]exec
2560 • [no]suid
2562 • [r]bind
2564 • [r]shared|[r]slave|[r]private[r]unbindable
2566 • idmap[=options]
2568 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2572 ume is mounted into the container at this directory.
2573 If a volume source is specified, it must be a path on the host or the
2576 name of a named volume. Host paths are allowed to be absolute or rela‐
2577 tive; relative paths are resolved relative to the directory Podman is
2578 run in. If the source does not exist, Podman returns an error. Users
2579 must pre-create the source files or directories.
2580 Any source that does not begin with a . or / is treated as the name of
2583 a named volume. If a volume with that name does not exist, it is cre‐
2584 ated. Volumes created with names are not anonymous, and they are not
2585 removed by the --rm option and the podman rm --volumes command.
2586 Specify multiple -v options to mount one or more volumes into a con‐
2589 tainer.
2590 Write Protected Volume Mounts
2593 Add :ro or :rw option to mount a volume in read-only or read-write
2596 mode, respectively. By default, the volumes are mounted read-write.
2597 See examples.
2598 Chowning Volume Mounts
2601 By default, Podman does not change the owner and group of source volume
2604 directories mounted into containers. If a container is created in a new
2605 user namespace, the UID and GID in the container may correspond to an‐
2606 other UID and GID on the host.
2607 The :U suffix tells Podman to use the correct host UID and GID based on
2610 the UID and GID within the container, to change recursively the owner
2611 and group of the source volume. Chowning walks the file system under
2612 the volume and changes the UID/GID on each file. If the volume has
2613 thousands of inodes, this process takes a long time, delaying the start
2614 of the container.
2615 Warning use with caution since this modifies the host filesystem.
2618 Labeling Volume Mounts
2621 Labeling systems like SELinux require that proper labels are placed on
2624 volume content mounted into a container. Without a label, the security
2625 system might prevent the processes running inside the container from
2626 using the content. By default, Podman does not change the labels set by
2627 the OS.
2628 To change a label in the container context, add either of two suffixes
2631 :z or :Z to the volume mount. These suffixes tell Podman to relabel
2632 file objects on the shared volumes. The z option tells Podman that two
2633 or more containers share the volume content. As a result, Podman labels
2634 the content with a shared content label. Shared volume labels allow all
2635 containers to read/write content. The Z option tells Podman to label
2636 the content with a private unshared label Only the current container
2637 can use a private volume. Relabeling walks the file system under the
2638 volume and changes the label on each file, if the volume has thousands
2639 of inodes, this process takes a long time, delaying the start of the
2640 container. If the volume was previously relabeled with the z option,
2641 Podman is optimized to not relabel a second time. If files are moved
2642 into the volume, then the labels can be manually change with the chcon
2643 -Rt container_file_t PATH command.
2644 Note: Do not relabel system files and directories. Relabeling system
2647 content might cause other confined services on the machine to fail.
2648 For these types of containers we recommend disabling SELinux separa‐
2649 tion. The option --security-opt label=disable disables SELinux separa‐
2650 tion for the container. For example if a user wanted to volume mount
2651 their entire home directory into a container, they need to disable
2652 SELinux separation.
2653 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2655 Overlay Volume Mounts
2659 The :O flag tells Podman to mount the directory from the host as a tem‐
2662 porary storage using the overlay file system. The container processes
2663 can modify content within the mountpoint which is stored in the con‐
2664 tainer storage in a separate directory. In overlay terms, the source
2665 directory is the lower, and the container storage directory is the up‐
2666 per. Modifications to the mount point are destroyed when the container
2667 finishes executing, similar to a tmpfs mount point being unmounted.
2668 For advanced users, the overlay option also supports custom non-
2671 volatile upperdir and workdir for the overlay mount. Custom upperdir
2672 and workdir can be fully managed by the users themselves, and Podman
2673 does not remove it on lifecycle completion. Example :O,up‐
2674 perdir=/some/upper,workdir=/some/work
2675 Subsequent executions of the container sees the original source direc‐
2678 tory content, any changes from previous container executions no longer
2679 exist.
2680 One use case of the overlay mount is sharing the package cache from the
2683 host into the container to allow speeding up builds.
2684 Note: The O flag conflicts with other options listed above.
2687 Content mounted into the container is labeled with the private label.
2690 On SELinux systems, labels in the source directory must be read‐
2691 able by the container label. Usually containers can read/execute con‐
2692 tainer_share_t and can read/write container_file_t. If unable to change
2693 the labels on a source volume, SELinux container separation must be
2694 disabled for the container to work.
2695 - Do not modify the source directory mounted into the container
2696 with an overlay mount, it can cause unexpected failures. Only modify
2697 the directory after the container finishes running.
2698 Mounts propagation
2701 By default bind mounted volumes are private. That means any mounts done
2704 inside the container is not visible on host and vice versa. One can
2705 change this behavior by specifying a volume mount propagation property.
2706 Making a volume shared mounts done under that volume inside the con‐
2707 tainer is visible on host and vice versa. Making a volume slave enables
2708 only one way mount propagation and that is mounts done on host under
2709 that volume is visible inside container but not the other way around.
2710 [1] ⟨#Footnote1⟩
2711 To control mount propagation property of a volume one can use the
2714 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2715 Propagation property can be specified only for bind mounted volumes and
2716 not for internal volumes or named volumes. For mount propagation to
2717 work the source mount point (the mount point where source dir is
2718 mounted on) has to have the right propagation properties. For shared
2719 volumes, the source mount point has to be shared. And for slave vol‐
2720 umes, the source mount point has to be either shared or slave. [1]
2721 ⟨#Footnote1⟩
2722 To recursively mount a volume and all of its submounts into a con‐
2725 tainer, use the rbind option. By default the bind option is used, and
2726 submounts of the source directory is not mounted into the container.
2727 Mounting the volume with a copy option tells podman to copy content
2730 from the underlying destination directory onto newly created internal
2731 volumes. The copy only happens on the initial creation of the volume.
2732 Content is not copied up when the volume is subsequently used on dif‐
2733 ferent containers. The copy option is ignored on bind mounts and has no
2734 effect.
2735 Mounting volumes with the nosuid options means that SUID executables on
2738 the volume can not be used by applications to change their privilege.
2739 By default volumes are mounted with nosuid.
2740 Mounting the volume with the noexec option means that no executables on
2743 the volume can be executed within the container.
2744 Mounting the volume with the nodev option means that no devices on the
2747 volume can be used by processes within the container. By default vol‐
2748 umes are mounted with nodev.
2749 If the HOST-DIR is a mount point, then dev, suid, and exec options are
2752 ignored by the kernel.
2753 Use df HOST-DIR to figure out the source mount, then use findmnt -o
2756 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2757 ties of source mount. If findmnt[4m(1) utility is not available, then one
2758 can look at the mount entry for the source mount point in
2759 /proc/self/mountinfo. Look at the "optional fields" and see if any
2760 propagation properties are specified. In there, shared:N means the
2761 mount is shared, master:N means mount is slave, and if nothing is
2762 there, the mount is private. [1] ⟨#Footnote1⟩
2763 To change propagation properties of a mount point, use mount(8) com‐
2766 mand. For example, if one wants to bind mount source directory /foo,
2767 one can do mount --bind /foo /foo and mount --make-private --make-
2768 shared /foo. This converts /foo into a shared mount point. Alterna‐
2769 tively, one can directly change propagation properties of source mount.
2770 Say / is source mount for /foo, then use mount --make-shared / to con‐
2771 vert / into a shared mount.
2772 Note: if the user only has access rights via a group, accessing the
2775 volume from inside a rootless container fails.
2776 Idmapped mount
2779 If idmap is specified, create an idmapped mount to the target user
2782 namespace in the container. The idmap option supports a custom mapping
2783 that can be different than the user namespace used by the container.
2784 The mapping can be specified after the idmap option like:
2785 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
2786 value is the start of the backing file system IDs that are mapped to
2787 the second value on the host. The length of this mapping is given in
2788 the third value. Multiple ranges are separated with #.
2789 Use the --group-add keep-groups option to pass the user's supplementary
2792 group access into the container.
2793 --volumes-from=CONTAINER[:OPTIONS]
2796 Mount volumes from the specified container(s). Used to share volumes
2797 between containers. The options is a comma-separated list with the fol‐
2798 lowing available elements:
2799 • rw|ro
2802 • z
2804 Mounts already mounted volumes from a source container onto another
2808 container. CONTAINER may be a name or ID. To share a volume, use the
2809 --volumes-from option when running the target container. Volumes can be
2810 shared even if the source container is not running.
2811 By default, Podman mounts the volumes in the same mode (read-write or
2814 read-only) as it is mounted in the source container. This can be
2815 changed by adding a ro or rw option.
2816 Labeling systems like SELinux require that proper labels are placed on
2819 volume content mounted into a container. Without a label, the security
2820 system might prevent the processes running inside the container from
2821 using the content. By default, Podman does not change the labels set by
2822 the OS.
2823 To change a label in the container context, add z to the volume mount.
2826 This suffix tells Podman to relabel file objects on the shared volumes.
2827 The z option tells Podman that two entities share the volume content.
2828 As a result, Podman labels the content with a shared content label.
2829 Shared volume labels allow all containers to read/write content.
2830 If the location of the volume from the source container overlaps with
2833 data residing on a target container, then the volume hides that data on
2834 the target.
2835 --workdir, -w=dir
2838 Working directory inside the container.
2839 The default working directory for running binaries within a container
2842 is the root directory (/). The image developer can set a different de‐
2843 fault with the WORKDIR instruction. The operator can override the work‐
2844 ing directory by using the -w option.
2845
2848 Create a container using a local image
2849 $ podman create alpine ls
2850 Create a container using a local image and annotate it
2854 $ podman create --annotation HELLO=WORLD alpine ls
2855 Create a container using a local image, allocating a pseudo-TTY, keeping
2859 stdin open and name it myctr
2860 podman create -t -i --name myctr alpine ls
2861 Set UID/GID mapping in a new user namespace
2865 Running a container in a new user namespace requires a mapping of the
2866 UIDs and GIDs from the host.
2867 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2869 Setting automatic user namespace separated containers
2873 # podman create --userns=auto:size=65536 ubi8-init
2874 Configure timezone in a container
2878 $ podman create --tz=local alpine date
2879 $ podman create --tz=Asia/Shanghai alpine date
2880 $ podman create --tz=US/Eastern alpine date
2881 Adding dependency containers
2885 Podman makes sure the first container, container1, is running before
2886 the second container (container2) is started.
2887 $ podman create --name container1 -t -i fedora bash
2889 $ podman create --name container2 --requires container1 -t -i fedora bash
2890 $ podman start --attach container2
2891 Multiple containers can be required.
2895 $ podman create --name container1 -t -i fedora bash
2897 $ podman create --name container2 -t -i fedora bash
2898 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2899 $ podman start --attach container3
2900 Exposing shared libraries inside of container as read-only using a glob
2904 $ podman create --mount type=glob,src=/usr/lib64/libnvidia\*,ro -i -t fedora /bin/bash
2905 Configure keep supplemental groups for access to volume
2909 $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2910 Configure execution domain for containers using personality flag
2914 $ podman create --name container1 --personality=LINUX32 fedora bash
2915 Create a container with external rootfs mounted as an overlay
2919 $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2920 Create a container connected to two networks (called net1 and net2) with a
2924 static ip
2925 $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2926 Rootless Containers
2930 Podman runs as a non-root user on most systems. This feature requires
2931 that a new enough version of shadow-utils be installed. The shadow-
2932 utils package must include the newuidmap and newgidmap executables.
2933 In order for users to run rootless, there must be an entry for their
2936 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2937 user namespace.
2938 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2941 packages are installed. The fuse-overlayfs package provides a
2942 userspace overlay storage driver, otherwise users need to use the vfs
2943 storage driver, which can be disk space expensive and less performant
2944 than other drivers.
2945 To enable VPN on the container, slirp4netns or pasta needs to be speci‐
2948 fied; without either, containers need to be run with the --network=host
2949 flag.
2950
2953 Environment variables within containers can be set using multiple dif‐
2954 ferent options: This section describes the precedence.
2955 Precedence order (later entries override earlier entries):
2958 • --env-host : Host environment of the process executing Podman
2961 is added.
2962 • --http-proxy: By default, several environment variables are
2964 passed in from the host, such as http_proxy and no_proxy. See
2965 --http-proxy for details.
2966 • Container image : Any environment variables specified in the
2968 container image.
2969 • --env-file : Any environment variables specified via env-
2971 files. If multiple files specified, then they override each
2972 other in order of entry.
2973 • --env : Any environment variables specified overrides previous
2975 settings.
2976 Create containers and set the environment ending with a *. The trail‐
2980 ing * glob functionality is only active when no value is specified:
2981 $ export ENV1=a
2983 $ podman create --name ctr1 --env 'ENV*' alpine env
2984 $ podman start --attach ctr1 | grep ENV
2985 ENV1=a
2986 $ podman create --name ctr2 --env 'ENV*=b' alpine env
2987 $ podman start --attach ctr2 | grep ENV
2988 ENV*=b
2989
2993 When Podman starts a container it actually executes the conmon program,
2994 which then executes the OCI Runtime. Conmon is the container monitor.
2995 It is a small program whose job is to watch the primary process of the
2996 container, and if the container dies, save the exit code. It also
2997 holds open the tty of the container, so that it can be attached to
2998 later. This is what allows Podman to run in detached mode (back‐
2999 grounded), so Podman can exit but conmon continues to run. Each con‐
3000 tainer has their own instance of conmon. Conmon waits for the container
3001 to exit, gathers and saves the exit code, and then launches a Podman
3002 process to complete the container cleanup, by shutting down the network
3003 and storage. For more information about conmon, see the conmon(8) man
3004 page.
3005
3008 /etc/subuid /etc/subgid
3009 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
3012 age location of downloaded container images. Podman defaults to use
3013 /var/tmp.
3014
3017 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
3018 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
3019 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
3020 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
3021 slirp4netns(1), pasta(1), fuse-overlayfs(1), proc(5), conmon(8), per‐
3022 sonality(2)
3023
3026 October 2017, converted from Docker documentation to Podman by Dan
3027 Walsh for Podman <dwalsh@redhat.com>
3028 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
3031 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
3034 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
3037
3040 1: The Podman project is committed to inclusivity, a core value of open
3041 source. The master and slave mount propagation terminology used here is
3042 problematic and divisive, and needs to be changed. However, these terms
3043 are currently used within the Linux kernel and must be used as-is at
3044 this time. When the kernel maintainers rectify this usage, Podman will
3045 follow suit immediately.
3046 podman-create(1)