1podman-create(1)() 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. You can then use the podman start container
21 command to 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 will be used by
36 default. For remote Podman, including Mac and Windows (excluding WSL2)
37 machines, docker is the only allowed transport.
38 dir:path
41 An existing local directory path storing the manifest, layer tarballs
42 and signatures as individual files. This is a non-standardized format,
43 primarily useful for debugging or noninvasive container inspection.
44 $ podman save --format docker-dir fedora -o /tmp/fedora
47 $ podman create dir:/tmp/fedora echo hello
48 docker://docker-reference (Default)
52 An image reference stored in a remote container image registry. Ex‐
53 ample: "quay.io/podman/stable:latest". The reference can include a
54 path to a specific registry; if it does not, the registries listed in
55 registries.conf will be queried to find a matching image. By default,
56 credentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
57 ers/auth.json by default) will be used to authenticate; otherwise it
58 falls back to using credentials in $HOME/.docker/config.json.
59 $ podman create registry.fedoraproject.org/fedora:latest echo hello
62 docker-archive:path[:docker-reference] An image stored in the docker
66 save formatted file. docker-reference is only used when creating such a
67 file, and it must not contain a digest.
68 $ podman save --format docker-archive fedora -o /tmp/fedora
71 $ podman create docker-archive:/tmp/fedora echo hello
72 docker-daemon:docker-reference
76 An image in docker-reference format stored in the docker daemon in‐
77 ternal storage. The docker-reference can also be an image ID (docker-
78 daemon:algo:digest).
79 $ sudo docker pull fedora
82 $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83 oci-archive:path:tag
87 An image in a directory compliant with the "Open Container Image Lay‐
88 out Specification" at the specified path and specified with a tag.
89 $ podman save --format oci-archive fedora -o /tmp/fedora
92 $ podman create oci-archive:/tmp/fedora echo hello
93
97 --add-host=host
98 Add a custom host-to-IP mapping (host:ip)
99 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102 tion can be set multiple times.
103 --annotation=key=value
106 Add an annotation to the container. The format is key=value. The --an‐
107 notation option can be set multiple times.
108 --arch=ARCH
111 Override the architecture, defaults to hosts, of the image to be
112 pulled. For example, arm.
113 --attach, -a=location
116 Attach to STDIN, STDOUT or STDERR.
117 In foreground mode (the default when -d is not specified), podman run
120 can start the process in the container and attach the console to the
121 process's standard input, output, and standard error. It can even pre‐
122 tend to be a TTY (this is what most command line executables expect)
123 and pass along signals. The -a option can be set for each of stdin,
124 stdout, and stderr.
125 --authfile=path
128 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
129 ers/auth.json
130 Note: You can also override the default path of the authentication file
133 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
134 ISTRY_AUTH_FILE=path
135 --blkio-weight=weight
138 Block IO weight (relative weight) accepts a weight value between 10 and
139 1000.
140 --blkio-weight-device=weight
143 Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
144 --cap-add=capability
147 Add Linux capabilities
148 --cap-drop=capability
151 Drop Linux capabilities
152 --cgroup-conf=KEY=VALUE
155 When running on cgroup v2, specify the cgroup file to write to and its
156 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
157 ory.high limit to 1GB.
158 --cgroup-parent=path
161 Path to cgroups under which the cgroup for the container will be cre‐
162 ated. If the path is not absolute, the path is considered to be rela‐
163 tive to the cgroups path of the init process. Cgroups will be created
164 if they do not already exist.
165 --cgroupns=mode
168 Set the cgroup namespace mode for the container.
169 host: use the host's cgroup namespace inside the container.
170 container:<NAME|ID>: join the namespace of the specified container.
171 ns:<PATH>: join the namespace at the specified path.
172 private: create a new cgroup namespace.
173 If the host uses cgroups v1, the default is set to host. On cgroups v2
176 the default is private.
177 --cgroups=mode
180 Determines whether the container will create CGroups. Valid values are
181 enabled, disabled, no-conmon, split, with the default being enabled.
182 The enabled option will create a new cgroup under the cgroup-parent.
185 The disabled option will force the container to not create CGroups, and
186 thus conflicts with CGroup options (--cgroupns and --cgroup-parent).
187 The no-conmon option disables a new CGroup only for the conmon process.
188 The split option splits the current cgroup in two sub-cgroups: one for
189 conmon and one for the container payload. It is not possible to set
190 --cgroup-parent with split.
191 --chrootdirs=path
194 Path to a directory inside the container that should be treated as a
195 chroot directory. Any Podman managed file (e.g., /etc/resolv.conf,
196 /etc/hosts, etc/hostname) that is mounted into the root directory will
197 be mounted into that location as well. Multiple directories should be
198 separated with a comma.
199 --cidfile=id
202 Write the container ID to the file
203 --conmon-pidfile=path
206 Write the pid of the conmon process to a file. conmon runs in a sepa‐
207 rate process than Podman, so this is necessary when using systemd to
208 restart Podman containers. (This option is not available with the re‐
209 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
210 chines)
211 --cpu-period=limit
214 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
215 duration in microseconds. Once the container's CPU quota is used up, it
216 will not be scheduled to run until the current period ends. Defaults to
217 100000 microseconds.
218 On some systems, changing the CPU limits may not be allowed for non-
221 root users. For more details, see https://github.com/containers/pod‐
222 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
223 fails-with-a-permissions-error
224 --cpu-quota=limit
227 Limit the CPU Completely Fair Scheduler (CFS) quota.
228 Limit the container's CPU usage. By default, containers run with the
231 full CPU resource. The limit is a number in microseconds. If you pro‐
232 vide a number, the container will be allowed to use that much CPU time
233 until the CPU period ends (controllable via --cpu-period).
234 On some systems, changing the CPU limits may not be allowed for non-
237 root users. For more details, see https://github.com/containers/pod‐
238 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
239 fails-with-a-permissions-error
240 --cpu-rt-period=microseconds
243 Limit the CPU real-time period in microseconds
244 Limit the container's Real Time CPU usage. This flag tell the kernel to
247 restrict the container's Real Time CPU usage to the period you specify.
248 This flag is not supported on cgroups V2 systems.
251 --cpu-rt-runtime=microseconds
254 Limit the CPU real-time runtime in microseconds
255 Limit the containers Real Time CPU usage. This flag tells the kernel to
258 limit the amount of time in a given CPU period Real Time tasks may con‐
259 sume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
260 this container could consume 95% of available CPU and leave the remain‐
261 ing 5% to normal priority tasks.
262 The sum of all runtimes across containers cannot exceed the amount al‐
265 lotted to the parent cgroup.
266 This flag is not supported on cgroups V2 systems.
269 --cpu-shares=shares
272 CPU shares (relative weight)
273 By default, all containers get the same proportion of CPU cycles. This
276 proportion can be modified by changing the container's CPU share
277 weighting relative to the weighting of all other running containers.
278 To modify the proportion from the default of 1024, use the --cpu-shares
281 flag to set the weighting to 2 or higher.
282 The proportion will only apply when CPU-intensive processes are run‐
285 ning. When tasks in one container are idle, other containers can use
286 the left-over CPU time. The actual amount of CPU time will vary depend‐
287 ing on the number of containers running on the system.
288 For example, consider three containers, one has a cpu-share of 1024 and
291 two others have a cpu-share setting of 512. When processes in all three
292 containers attempt to use 100% of CPU, the first container would re‐
293 ceive 50% of the total CPU time. If you add a fourth container with a
294 cpu-share of 1024, the first container only gets 33% of the CPU. The
295 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
296 On a multi-core system, the shares of CPU time are distributed over all
299 CPU cores. Even if a container is limited to less than 100% of CPU
300 time, it can use 100% of each individual CPU core.
301 For example, consider a system with more than three cores. If you start
304 one container {C0} with -c=512 running one process, and another con‐
305 tainer {C1} with -c=1024 running two processes, this can result in the
306 following division of CPU shares:
307 PID container CPU CPU share 100 {C0} 0 100% of
310 CPU0 101 {C1} 1 100% of CPU1 102
311 {C1} 2 100% of CPU2
312 --cpus=number
315 Number of CPUs. The default is 0.0 which means no limit. This is short‐
316 hand for --cpu-period and --cpu-quota, so you may only set either
317 --cpus or --cpu-period and --cpu-quota.
320 On some systems, changing the CPU limits may not be allowed for non-
321 root users. For more details, see https://github.com/containers/pod‐
322 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
323 fails-with-a-permissions-error
324 --cpuset-cpus=cpus
327 CPUs in which to allow execution (0-3, 0,1)
328 --cpuset-mems=nodes
331 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
332 tive on NUMA systems.
333 If you have four memory nodes on your system (0-3), use --cpuset-
336 mems=0,1 then processes in your container will only use memory from the
337 first two memory nodes.
338 --device=host-device[:container-device][:permissions]
341 Add a host device to the container. Optional permissions parameter can
342 be used to specify device permissions, it is combination of r for read,
343 w for write, and m for mknod(2).
344 Example: --device=/dev/sdc:/dev/xvdc:rwm.
347 Note: if _hostdevice is a symbolic link then it will be resolved first.
350 The container will only store the major and minor numbers of the host
351 device.
352 Note: if the user only has access rights via a group, accessing the de‐
355 vice from inside a rootless container will fail. Use the --group-add
356 keep-groups flag to pass the user's supplementary group access into the
357 container.
358 Podman may load kernel modules required for using the specified device.
361 The devices that podman will load modules when necessary are:
362 /dev/fuse.
363 --device-cgroup-rule="type major:minor mode"
366 Add a rule to the cgroup allowed devices list. The rule is expected to
367 be in the format specified in the Linux kernel documentation (Documen‐
368 tation/cgroup-v1/devices.txt):
369 - type: a (all), c (char), or b (block);
370 - major and minor: either a number, or * for all;
371 - mode: a composition of r (read), w (write), and m (mknod(2)).
372 --device-read-bps=path
375 Limit read rate (bytes per second) from a device (e.g. --device-read-
376 bps=/dev/sda:1mb)
377 --device-read-iops=path
380 Limit read rate (IO per second) from a device (e.g. --device-read-
381 iops=/dev/sda:1000)
382 --device-write-bps=path
385 Limit write rate (bytes per second) to a device (e.g. --device-write-
386 bps=/dev/sda:1mb)
387 --device-write-iops=path
390 Limit write rate (IO per second) to a device (e.g. --device-write-
391 iops=/dev/sda:1000)
392 --disable-content-trust
395 This is a Docker specific option to disable image verification to a
396 Docker registry and is not supported by Podman. This flag is a NOOP and
397 provided solely for scripting compatibility.
398 --dns=dns
401 Set custom DNS servers. Invalid if using --dns and --network that is
402 set to 'none' or container:<name|id>.
403 This option can be used to override the DNS configuration passed to the
406 container. Typically this is necessary when the host DNS configuration
407 is invalid for the container (e.g., 127.0.0.1). When this is the case
408 the --dns flag is necessary for every run.
409 The special value none can be specified to disable creation of /etc/re‐
412 solv.conf in the container by Podman. The /etc/resolv.conf file in the
413 image will be used without changes.
414 --dns-opt=option
417 Set custom DNS options. Invalid if using --dns-opt and --network that
418 is set to 'none' or container:<name|id>.
419 --dns-search=domain
422 Set custom DNS search domains. Invalid if using --dns-search and --net‐
423 work that is set to 'none' or container:<name|id>. (Use --dns-search=.
424 if you don't wish to set the search domain)
425 --entrypoint="command" | '["command", arg1 , ...]'
428 Overwrite the default ENTRYPOINT of the image
429 This option allows you to overwrite the default entrypoint of the im‐
432 age. The ENTRYPOINT of an image is similar to a COMMAND because it
433 specifies what executable to run when the container starts, but it is
434 (purposely) more difficult to override. The ENTRYPOINT gives a con‐
435 tainer its default nature or behavior, so that when you set an ENTRY‐
436 POINT you can run the container as if it were that binary, complete
437 with default options, and you can pass in more options via the COMMAND.
438 But, sometimes an operator may want to run something else inside the
439 container, so you can override the default ENTRYPOINT at runtime by us‐
440 ing a --entrypoint and a string to specify the new ENTRYPOINT.
441 You need to specify multi option commands in the form of a json string.
444 --env, -e=env
447 Set environment variables
448 This option allows arbitrary environment variables that are available
451 for the process to be launched inside of the container. If an environ‐
452 ment variable is specified without a value, Podman will check the host
453 environment for a value and set the variable only if it is set on the
454 host. If an environment variable ending in * is specified, Podman will
455 search the host environment for variables starting with the prefix and
456 will add those variables to the container. If an environment variable
457 with a trailing ***** is specified, then a value must be supplied.
458 See Environment ⟨#environment⟩ note below for precedence and examples.
461 --env-file=file
464 Read in a line delimited file of environment variables. See Environment
465 note below for precedence.
466 --env-host
469 Use host environment inside of the container. See Environment note be‐
470 low for precedence. (This option is not available with the remote Pod‐
471 man client, including Mac and Windows (excluding WSL2) machines)
472 --expose=port
475 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
476 port redirection on the host system.
477 --gidmap=container_gid:host_gid:amount
480 GID map for the user namespace. Using this flag will run the container
481 with user namespace enabled. It conflicts with the --userns and --sub‐
482 gidname flags.
483 The following example maps uids 0-2000 in the container to the uids
486 30000-31999 on the host and gids 0-2000 in the container to the gids
487 30000-31999 on the host. --gidmap=0:30000:2000
488 Note: the --gidmap flag cannot be called in conjunction with the --pod
491 flag as a gidmap cannot be set on the container level when in a pod.
492 --group-add=group|keep-groups
495 Assign additional groups to the primary user running within the con‐
496 tainer process.
497 • keep-groups is a special flag that tells Podman to keep the
500 supplementary group access.
501 Allows container to use the user's supplementary group access. If file
505 systems or devices are only accessible by the rootless user's group,
506 this flag tells the OCI runtime to pass the group access into the con‐
507 tainer. Currently only available with the crun OCI runtime. Note: keep-
508 groups is exclusive, you cannot add any other groups with this flag.
509 (Not available for remote commands, including Mac and Windows (exclud‐
510 ing WSL2) machines)
511 --health-cmd="command" | '["command", arg1 , ...]'
514 Set or alter a healthcheck command for a container. The command is a
515 command to be executed inside your container that determines your con‐
516 tainer health. The command is required for other healthcheck options to
517 be applied. A value of none disables existing healthchecks.
518 Multiple options can be passed in the form of a JSON array; otherwise,
521 the command will be interpreted as an argument to /bin/sh -c.
522 --health-interval=interval
525 Set an interval for the healthchecks (a value of disable results in no
526 automatic timer setup) (default "30s")
527 --health-retries=retries
530 The number of retries allowed before a healthcheck is considered to be
531 unhealthy. The default value is 3.
532 --health-start-period=period
535 The initialization time needed for a container to bootstrap. The value
536 can be expressed in time format like 2m3s. The default value is 0s
537 --health-timeout=timeout
540 The maximum time allowed to complete the healthcheck before an interval
541 is considered failed. Like start-period, the value can be expressed in
542 a time format such as 1m22s. The default value is 30s.
543 --help
546 Print usage statement
547 --hostname=name, -h
550 Container host name
551 Sets the container host name that is available inside the container.
554 Can only be used with a private UTS namespace --uts=private (default).
555 If --pod is specified and the pod shares the UTS namespace (default)
556 the pod's hostname will be used.
557 --hostuser=name
560 Add a user account to /etc/passwd from the host to the container. The
561 Username or UID must exist on the host system.
562 --http-proxy
565 By default proxy environment variables are passed into the container if
566 set for the Podman process. This can be disabled by setting the --http-
567 proxy option to false. The environment variables passed in include
568 http_proxy, https_proxy, ftp_proxy, no_proxy, and also the upper case
569 versions of those. This option is only needed when the host system must
570 use a proxy but the container should not use any proxy. Proxy environ‐
571 ment variables specified for the container in any other way will over‐
572 ride the values that would have been passed through from the host.
573 (Other ways to specify the proxy for the container include passing the
574 values with the --env flag, or hard coding the proxy environment at
575 container build time.) (This option is not available with the remote
576 Podman client, including Mac and Windows (excluding WSL2) machines)
577 For example, to disable passing these environment variables from host
580 to container:
581 --http-proxy=false
584 Defaults to true
587 --image-volume, builtin-volume=bind|tmpfs|ignore
590 Tells Podman how to handle the builtin image volumes. Default is bind.
591 • bind: An anonymous named volume will be created and mounted
594 into the container.
595 • tmpfs: The volume is mounted onto the container as a tmpfs,
597 which allows the users to create content that disappears when
598 the container is stopped.
599 • ignore: All volumes are just ignored and no action is taken.
601 --init
605 Run an init inside the container that forwards signals and reaps pro‐
606 cesses.
607 --init-ctr=type (pods only)
610 When using pods, create an init style container, which is run after the
611 infra container is started but before regular pod containers are
612 started. Init containers are useful for running setup operations for
613 the pod's applications.
614 Valid values for init-ctr type are always or once. The always value
617 means the container will run with each and every pod start, whereas the
618 once value means the container will only run once when the pod is
619 started and then the container is removed.
620 Init containers are only run on pod start. Restarting a pod will not
623 execute any init containers should they be present. Furthermore, init
624 containers can only be created in a pod when that pod is not running.
625 --init-path=path
628 Path to the container-init binary.
629 --interactive, -i
632 Keep STDIN open even if not attached. The default is false.
633 --ip=ipv4
636 Specify a static IPv4 address for the container, for example
637 10.88.64.128. This option can only be used if the container is joined
638 to only a single network - i.e., --network=network-name is used at most
639 once - and if the container is not joining another container's network
640 namespace via --network=container:id. The address must be within the
641 network's IP address pool (default 10.88.0.0/16).
642 To specify multiple static IP addresses per container, set multiple
645 networks using the --network option with a static IP address specified
646 for each using the ip mode for that option.
647 --ip6=ipv6
650 Specify a static IPv6 address for the container, for example
651 fd46:db93:aa76:ac37::10. This option can only be used if the container
652 is joined to only a single network - i.e., --network=network-name is
653 used at most once - and if the container is not joining another con‐
654 tainer's network namespace via --network=container:id. The address
655 must be within the network's IPv6 address pool.
656 To specify multiple static IPv6 addresses per container, set multiple
659 networks using the --network option with a static IPv6 address speci‐
660 fied for each using the ip6 mode for that option.
661 --ipc=ipc
664 Set the IPC namespace mode for a container. The default is to create a
665 private IPC namespace.
666 • "": Use Podman's default, defined in containers.conf.
669 • container:id: reuses another container's shared memory, sema‐
671 phores, and message queues
672 • host: use the host's shared memory, semaphores, and message
674 queues inside the container. Note: the host mode gives the
675 container full access to local shared memory and is therefore
676 considered insecure.
677 • none: private IPC namespace, with /dev/shm not mounted.
679 • ns:path: path to an IPC namespace to join.
681 • private: private IPC namespace. = shareable: private IPC
683 namespace with a possibility to share it with other contain‐
684 ers.
685 --label, -l=label
689 Add metadata to a container (e.g., --label com.example.key=value)
690 --label-file=file
693 Read in a line delimited file of labels
694 --link-local-ip=ip
697 Not implemented
698 --log-driver="k8s-file"
701 Logging driver for the container. Currently available options are k8s-
702 file, journald, none and passthrough, with json-file aliased to k8s-
703 file for scripting compatibility.
704 The podman info command below will display the default log-driver for
707 the system.
708 $ podman info --format '{{ .Host.LogDriver }}'
711 journald
712 The passthrough driver passes down the standard streams (stdin, stdout,
716 stderr) to the container. It is not allowed with the remote Podman
717 client, including Mac and Windows (excluding WSL2) machines, and on a
718 tty, since it is vulnerable to attacks via TIOCSTI.
719 --log-opt=name=value
722 Set custom logging configuration. The following *name*s are supported:
723 • path: specify a path to the log file (e.g. --log-opt
726 path=/var/log/container/mycontainer.json);
727 • max-size: specify a max size of the log file (e.g. --log-opt
729 max-size=10mb);
730 • tag: specify a custom log tag for the container (e.g. --log-
732 opt tag="{{.ImageName}}".
733 It supports the same keys as podman inspect --format.
737 This option is currently supported only by the journald log driver.
740 --mac-address=address
743 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
744 option can only be used if the container is joined to only a single
745 network - i.e., --network=network-name is used at most once - and if
746 the container is not joining another container's network namespace via
747 --network=container:id.
748 Remember that the MAC address in an Ethernet network must be unique.
751 The IPv6 link-local address will be based on the device's MAC address
752 according to RFC4862.
753 To specify multiple static MAC addresses per container, set multiple
756 networks using the --network option with a static MAC address specified
757 for each using the mac mode for that option.
758 --memory, -m=limit
761 Memory limit (format: <number>[<unit>], where unit = b (bytes), k
762 (kibibytes), m (mebibytes), or g (gibibytes))
763 Allows you to constrain the memory available to a container. If the
766 host supports swap memory, then the -m memory setting can be larger
767 than physical RAM. If a limit of 0 is specified (not using -m), the
768 container's memory is not limited. The actual limit may be rounded up
769 to a multiple of the operating system's page size (the value would be
770 very large, that's millions of trillions).
771 --memory-reservation=limit
774 Memory soft limit (format: <number>[<unit>], where unit = b (bytes), k
775 (kibibytes), m (mebibytes), or g (gibibytes))
776 After setting memory reservation, when the system detects memory con‐
779 tention or low memory, containers are forced to restrict their consump‐
780 tion to their reservation. So you should always set the value below
781 --memory, otherwise the hard limit will take precedence. By default,
782 memory reservation will be the same as memory limit.
783 --memory-swap=limit
786 A limit value equal to memory plus swap. Must be used with the -m
787 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
788 ory) value. By default, the swap LIMIT will be set to double the value
789 of --memory.
790 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
793 (kibibytes), m (mebibytes), or g (gibibytes). If you don't specify a
794 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
795 --memory-swappiness=number
798 Tune a container's memory swappiness behavior. Accepts an integer be‐
799 tween 0 and 100.
800 This flag is not supported on cgroups V2 systems.
803 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
806 Attach a filesystem mount to the container
807 Current supported mount TYPEs are bind, volume, image, tmpfs and de‐
810 vpts. [1] ⟨#Footnote1⟩
811 e.g.
814 type=bind,source=/path/on/host,destination=/path/in/container
816 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
818 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
820 type=volume,source=vol1,destination=/path/in/container,ro=true
822 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
824 type=image,source=fedora,destination=/fedora-image,rw=true
826 type=devpts,destination=/dev/pts
828 Common Options:
830 · src, source: mount source spec for bind and volume. Mandatory for bind.
832 · dst, destination, target: mount destination spec.
834 Options specific to volume:
836 · ro, readonly: true or false (default).
838 . 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.
840 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
842 Options specific to image:
844 · rw, readwrite: true or false (default).
846 Options specific to bind:
848 · ro, readonly: true or false (default).
850 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
852 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
854 . relabel: shared, private.
856 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
858 . 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.
860 Options specific to tmpfs:
862 · ro, readonly: true or false (default).
864 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
866 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
868 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
870 · notmpcopyup: Disable copying files from the image to the tmpfs.
872 . 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.
874 Options specific to devpts:
876 · uid: UID of the file owner (default 0).
878 · gid: GID of the file owner (default 0).
880 · mode: permission mask for the file (default 600).
882 · max: maximum number of PTYs (default 1048576).
884 --name=name
888 Assign a name to the container
889 The operator can identify a container in three ways: UUID long identi‐
892 fier
893 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
894 UUID short identifier (“f78375b1c487”) Name (“jonah”)
895 podman generates a UUID for each container, and if a name is not as‐
898 signed to the container with --name then it will generate a random
899 string name. The name is useful any place you need to identify a con‐
900 tainer. This works for both background and foreground containers.
901 --network=mode, --net
904 Set the network mode for the container. Invalid if using --dns, --dns-
905 opt, or --dns-search with --network set to none or container:id. If
906 used together with --pod, the container will not join the pod's network
907 namespace.
908 Valid mode values are:
911 • bridge[:OPTIONS,...]: Create a network stack on the default
914 bridge. This is the default for rootful containers. It is pos‐
915 sible to specify these additional options:
916 • alias=name: Add network-scoped alias for the container.
918 • ip=IPv4: Specify a static ipv4 address for this container.
920 • ip=IPv6: Specify a static ipv6 address for this container.
922 • mac=MAC: Specify a static mac address for this container.
924 • interface_name: Specify a name for the created network in‐
926 terface inside the container.
927 For example to set a static ipv4 address and a static mac address, use
933 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99. - <network name
934 or ID>[:OPTIONS,...]: Connect to a user-defined network; this is the
935 network name or ID from a network created by podman network create. Us‐
936 ing the network name implies the bridge network mode. It is possible to
937 specify the same options described under the bridge mode above. You can
938 use the --network option multiple times to specify additional networks.
939 - none: Create a network namespace for the container but do not config‐
940 ure network interfaces for it, thus the container has no network con‐
941 nectivity. - container:id: Reuse another container's network stack. -
942 host: Do not create a network namespace, the container will use the
943 host's network. Note: The host mode gives the container full access to
944 local system services such as D-bus and is therefore considered inse‐
945 cure. - ns:path: Path to a network namespace to join. - private: Cre‐
946 ate a new namespace for the container. This will use the bridge mode
947 for rootful containers and slirp4netns for rootless ones. -
948 slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user network
949 stack. This is the default for rootless containers. It is possible to
950 specify these additional options, they can also be set with net‐
951 work_cmd_options in containers.conf:
952 - allow_host_loopback=true|false: Allow the slirp4netns to reach the
953 host loopback IP (10.0.2.2). Default is false.
954 - mtu=MTU: Specify the MTU to use for this network. (Default is
955 65520).
956 - cidr=CIDR: Specify ip range to use for this network. (Default is
957 10.0.2.0/24).
958 - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
959 outbound_addr6).
960 - outbound_addr=INTERFACE: Specify the outbound interface slirp
961 should bind to (ipv4 traffic only).
962 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
963 bind to.
964 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
965 should bind to (ipv6 traffic only).
966 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
967 bind to.
968 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
969 fault.
970 Note: Rootlesskit changes the source IP address of incoming packets
971 to an IP address in the container network namespace, usually
972 10.0.2.100. If your application requires the real source IP address,
973 e.g. web server logs, use the slirp4netns port handler. The rootlesskit
974 port handler is also used for rootless containers when connected to
975 user-defined networks.
976 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
977 is slower than rootlesskit but preserves the correct source IP address.
978 This port handler cannot be used for user-defined networks.
979 --network-alias=alias
982 Add a network-scoped alias for the container, setting the alias for all
983 networks that the container joins. To set a name only for a specific
984 network, use the alias option as described under the --network option.
985 Network aliases work only with the bridge networking mode. This option
986 can be specified multiple times. NOTE: A container will only have ac‐
987 cess to aliases on the first network that it joins. This is a limita‐
988 tion that will be removed in a later release.
989 --no-healthcheck
992 Disable any defined healthchecks for container.
993 --no-hosts
996 Do not create /etc/hosts for the container. By default, Podman will
997 manage /etc/hosts, adding the container's own IP address and any hosts
998 from --add-host. --no-hosts disables this, and the image's /etc/hosts
999 will be preserved unmodified. This option conflicts with --add-host.
1000 --oom-kill-disable
1003 Whether to disable OOM Killer for the container or not.
1004 This flag is not supported on cgroups V2 systems.
1007 --oom-score-adj=num
1010 Tune the host's OOM preferences for containers (accepts -1000 to 1000)
1011 --os=OS
1014 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1015 ample, windows.
1016 --passwd-entry=ENTRY
1019 Customize the entry that is written to the /etc/passwd file within the
1020 container when --passwd is used.
1021 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1024 placed with their value at runtime.
1025 --personality=persona
1028 Personality sets the execution domain via Linux personality(2).
1029 --pid=pid
1032 Set the PID mode for the container Default is to create a private PID
1033 namespace for the container - container:<name|id>: join another con‐
1034 tainer's PID namespace - host: use the host's PID namespace for the
1035 container. Note: the host mode gives the container full access to local
1036 PID and is therefore considered insecure. - ns: join the specified PID
1037 namespace - private: create a new namespace for the container (default)
1038 --pidfile=path
1041 When the pidfile location is specified, the container process' PID will
1042 be written to the pidfile. (This option is not available with the re‐
1043 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
1044 chines) If the pidfile option is not specified, the container process'
1045 PID will be written to /run/containers/storage/${storage-driver}-con‐
1046 tainers/$CID/userdata/pidfile.
1047 After the container is started, the location for the pidfile can be
1050 discovered with the following podman inspect command:
1051 $ podman inspect --format '{{ .PidFile }}' $CID
1054 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1055 --pids-limit=limit
1059 Tune the container's pids limit. Set -1 to have unlimited pids for the
1060 container. (default "4096" on systems that support PIDS cgroups).
1061 --platform=OS/ARCH
1064 Specify the platform for selecting the image. (Conflicts with --arch
1065 and --os) The --platform option can be used to override the current ar‐
1066 chitecture and operating system.
1067 --pod=name
1070 Run container in an existing pod. If you want Podman to make the pod
1071 for you, preference the pod name with new:. To make a pod with more
1072 granular options, use the podman pod create command before creating a
1073 container.
1074 --pod-id-file=path
1077 Run container in an existing pod and read the pod's ID from the speci‐
1078 fied file. If a container is run within a pod, and the pod has an in‐
1079 fra-container, the infra-container will be started before the container
1080 is.
1081 --privileged
1084 Give extended privileges to this container. The default is false.
1085 By default, Podman containers are “unprivileged” (=false) and cannot,
1088 for example, modify parts of the operating system. This is because by
1089 default a container is not allowed to access any devices. A “privi‐
1090 leged” container is given access to all devices.
1091 When the operator executes a privileged container, Podman enables ac‐
1094 cess to all devices on the host, turns off graphdriver mount options,
1095 as well as turning off most of the security measures protecting the
1096 host from the container.
1097 Rootless containers cannot have more privileges than the account that
1100 launched them.
1101 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1104 Publish a container's port, or range of ports, to the host.
1105 Both hostPort and containerPort can be specified as a range of ports.
1108 When specifying ranges for both, the number of container ports in the
1109 range must match the number of host ports in the range.
1110 If host IP is set to 0.0.0.0 or not set at all, the port will be bound
1113 on all IPs on the host.
1114 By default, Podman will publish TCP ports. To publish a UDP port in‐
1117 stead, give udp as protocol. To publish both TCP and UDP ports, set
1118 --publish twice, with tcp, and udp as protocols respectively. Rootful
1119 containers can also publish ports using the sctp protocol.
1120 Host port does not have to be specified (e.g. podman run -p
1123 127.0.0.1::80). If it is not, the container port will be randomly as‐
1124 signed a port on the host.
1125 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1128 TAINERPORT.
1129 Note: If a container will be run within a pod, it is not necessary to
1132 publish the port for the containers in the pod. The port must only be
1133 published by the pod itself. Pod network stacks act like the network
1134 stack on the host - you have a variety of containers in the pod, and
1135 programs in the container, all sharing a single interface and IP ad‐
1136 dress, and associated ports. If one container binds to a port, no other
1137 container can use that port within the pod while it is in use. Contain‐
1138 ers in the pod can also communicate over localhost by having one con‐
1139 tainer bind to localhost in the pod, and another connect to that port.
1140 --publish-all, -P
1143 Publish all exposed ports to random ports on the host interfaces. The
1144 default is false.
1145 When set to true publish all exposed ports to the host interfaces. The
1148 default is false. If the operator uses -P (or -p) then Podman will make
1149 the exposed port accessible on the host and the ports will be available
1150 to any client that can reach the host. When using -P, Podman will bind
1151 any exposed port to a random port on the host within an ephemeral port
1152 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
1153 mapping between the host ports and the exposed ports, use podman port.
1154 --pull=missing
1157 Pull image before creating ("always"|"missing"|"never") (default "miss‐
1158 ing").
1159 'missing': default value, attempt to pull the latest image from
1160 the registries listed in registries.conf if a local image does not ex‐
1161 ist.Raise an error if the image is not in any listed registry and is
1162 not present locally.
1163 'always': Pull the image from the first registry it is found in
1164 as listed in registries.conf. Raise an error if not found in the reg‐
1165 istries, even if the image is present locally.
1166 'never': do not pull the image from the registry, use only the
1167 local version. Raise an error if the image is not present locally.
1168 Defaults to missing.
1171 --quiet, -q
1174 Suppress output information when pulling images
1175 --read-only
1178 Mount the container's root filesystem as read only.
1179 By default a container will have its root filesystem writable allowing
1182 processes to write files anywhere. By specifying the --read-only flag
1183 the container will have its root filesystem mounted as read only pro‐
1184 hibiting any writes.
1185 --read-only-tmpfs
1188 If container is running in --read-only mode, then mount a read-write
1189 tmpfs on /run, /tmp, and /var/tmp. The default is true
1190 --replace
1193 If another container with the same name already exists, replace and re‐
1194 move it. The default is false.
1195 --requires=container
1198 Specify one or more requirements. A requirement is a dependency con‐
1199 tainer that will be started before this container. Containers can be
1200 specified by name or ID, with multiple containers being separated by
1201 commas.
1202 --restart=policy
1205 Restart policy to follow when containers exit. Restart policy will not
1206 take effect if a container is stopped via the podman kill or podman
1207 stop commands.
1208 Valid values are:
1211 • no : Do not restart containers on exit
1214 • on-failure[:max_retries] : Restart containers when they exit
1216 with a non-0 exit code, retrying indefinitely or until the op‐
1217 tional max_retries count is hit
1218 • always : Restart containers when they exit,
1220 regardless of status, retrying indefinitely
1221 • unless-stopped : Identical to always
1223 Please note that restart will not restart containers after a system re‐
1227 boot. If this functionality is required in your environment, you can
1228 invoke Podman from a systemd unit file, or create an init script for
1229 whichever init system is in use. To generate systemd unit files,
1230 please see podman generate systemd
1231 --rm
1234 Automatically remove the container when it exits. The default is false.
1235 --rootfs
1238 If specified, the first argument refers to an exploded container on the
1239 file system.
1240 This is useful to run a container without requiring any image manage‐
1243 ment, the rootfs of the container is assumed to be managed externally.
1244 Overlay Rootfs Mounts
1247 The :O flag tells Podman to mount the directory from the rootfs path as
1250 storage using the overlay file system. The container processes can mod‐
1251 ify content within the mount point which is stored in the container
1252 storage in a separate directory. In overlay terms, the source directory
1253 will be the lower, and the container storage directory will be the up‐
1254 per. Modifications to the mount point are destroyed when the container
1255 finishes executing, similar to a tmpfs mount point being unmounted.
1256 --sdnotify=container|conmon|ignore
1259 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1260 Type=notify.
1261 Default is container, which means allow the OCI runtime to proxy the
1264 socket into the container to receive ready notification. Podman will
1265 set the MAINPID to conmon's pid. The conmon option sets MAINPID to
1266 conmon's pid, and sends READY when the container has started. The
1267 socket is never passed to the runtime or the container. The ignore op‐
1268 tion removes NOTIFY_SOCKET from the environment for itself and child
1269 processes, for the case where some other process above Podman uses NO‐
1270 TIFY_SOCKET and Podman should not use it.
1271 --seccomp-policy=policy
1274 Specify the policy to select the seccomp profile. If set to image, Pod‐
1275 man will look for a "io.containers.seccomp.profile" label in the con‐
1276 tainer-image config and use its value as a seccomp profile. Otherwise,
1277 Podman will follow the default policy by applying the default profile
1278 unless specified otherwise via --security-opt seccomp as described be‐
1279 low.
1280 Note that this feature is experimental and may change in the future.
1283 --secret=secret[,opt=opt ...]
1286 Give the container access to a secret. Can be specified multiple times.
1287 A secret is a blob of sensitive data which a container needs at runtime
1290 but should not be stored in the image or in source control, such as
1291 usernames and passwords, TLS certificates and keys, SSH keys or other
1292 important generic strings or binary content (up to 500 kb in size).
1293 When secrets are specified as type mount, the secrets are copied and
1296 mounted into the container when a container is created. When secrets
1297 are specified as type env, the secret will be set as an environment
1298 variable within the container. Secrets are written in the container at
1299 the time of container creation, and modifying the secret using podman
1300 secret commands after the container is created will not affect the se‐
1301 cret inside the container.
1302 Secrets and its storage are managed using the podman secret command.
1305 Secret Options
1308 • type=mount|env : How the secret will be exposed to the con‐
1311 tainer. Default mount.
1312 • target=target : Target of secret. Defaults to secret name.
1314 • uid=0 : UID of secret. Defaults to 0. Mount secret
1316 type only.
1317 • gid=0 : GID of secret. Defaults to 0. Mount secret
1319 type only.
1320 • mode=0 : Mode of secret. Defaults to 0444. Mount
1322 secret type only.
1323 --security-opt=option
1327 Security Options
1328 • apparmor=unconfined : Turn off apparmor confinement for the
1331 container
1332 • apparmor=your-profile : Set the apparmor confinement profile
1334 for the container
1335 • label=user:USER : Set the label user for the container
1337 processes
1338 • label=role:ROLE : Set the label role for the container
1340 processes
1341 • label=type:TYPE : Set the label process type for the con‐
1343 tainer processes
1344 • label=level:LEVEL : Set the label level for the container
1346 processes
1347 • label=filetype:TYPE : Set the label file type for the con‐
1349 tainer files
1350 • label=disable : Turn off label separation for the con‐
1352 tainer
1353 Note: Labeling can be disabled for all containers by setting la‐
1357 bel=false in the containers.conf (/etc/containers/containers.conf or
1358 $HOME/.config/containers/containers.conf) file.
1359 • mask=/path/1:/path/2 : The paths to mask separated by a colon.
1362 A masked path cannot be accessed inside the container.
1363 • no-new-privileges : Disable container processes from gaining
1365 additional privileges
1366 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1368 tainer.
1369 • seccomp=profile.json : JSON file to be used as a seccomp fil‐
1371 ter. Note that the io.podman.annotations.seccomp annotation is
1372 set with the specified value as shown in podman inspect.
1373 • proc-opts=OPTIONS : Comma-separated list of options to use for
1375 the /proc mount. More details for the possible mount options
1376 are specified in the proc(5) man page.
1377 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1379 (/proc/*): Paths to unmask separated by a colon. If set to
1380 ALL, it will unmask all the paths that are masked or made read
1381 only by default. The default masked paths are /proc/acpi,
1382 /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_de‐
1383 bug, /proc/scsi, /proc/timer_list, /proc/timer_stats,
1384 /sys/firmware, and /sys/fs/selinux. The default paths that
1385 are read only are /proc/asound, /proc/bus, /proc/fs,
1386 /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1387 Note: Labeling can be disabled for all containers by setting la‐
1391 bel=false in the containers.conf (/etc/containers/containers.conf or
1392 $HOME/.config/containers/containers.conf) file.
1393 --shm-size=size
1396 Size of /dev/shm (format: <number>[<unit>], where unit = b (bytes), k
1397 (kibibytes), m (mebibytes), or g (gibibytes)) If you omit the unit, the
1398 system uses bytes. If you omit the size entirely, the system uses 64m.
1399 When size is 0, there is no limit on the amount of memory used for IPC
1400 by the container.
1401 --stop-signal=SIGTERM
1404 Signal to stop a container. Default is SIGTERM.
1405 --stop-timeout=seconds
1408 Timeout (in seconds) to stop a container. Default is 10. Remote con‐
1409 nections use local containers.conf for defaults
1410 --subgidname=name
1413 Name for GID map from the /etc/subgid file. Using this flag will run
1414 the container with user namespace enabled. This flag conflicts with
1415 --userns and --gidmap.
1416 --subuidname=name
1419 Name for UID map from the /etc/subuid file. Using this flag will run
1420 the container with user namespace enabled. This flag conflicts with
1421 --userns and --uidmap.
1422 --sysctl=SYSCTL
1425 Configure namespaced kernel parameters at runtime
1426 IPC Namespace - current sysctls allowed:
1429 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
1432 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced Sysctls beginning
1433 with fs.mqueue.*
1434 Note: if you use the --ipc=host option these sysctls will not be al‐
1437 lowed.
1438 Network Namespace - current sysctls allowed:
1441 Sysctls beginning with net.*
1442 Note: if you use the --network=host option these sysctls will not be
1445 allowed.
1446 --systemd=true|false|always
1449 Run container in systemd mode. The default is true.
1450 The value always enforces the systemd mode is enforced without looking
1453 at the executable name. Otherwise, if set to true and the command you
1454 are running inside the container is systemd, /usr/sbin/init, /sbin/init
1455 or /usr/local/sbin/init.
1456 Running the container in systemd mode causes the following changes:
1459 • Podman mounts tmpfs file systems on the following directories
1462 • /run
1464 • /run/lock
1466 • /tmp
1468 • /sys/fs/cgroup/systemd
1470 • /var/lib/journal
1472 • Podman sets the default stop signal to SIGRTMIN+3.
1476 • Podman sets container_uuid environment variable in the con‐
1478 tainer to the first 32 characters of the container id.
1479 This allows systemd to run in a confined container without any modifi‐
1483 cations.
1484 Note: On SELinux systems, systemd attempts to write to the cgroup file
1487 system. Containers writing to the cgroup file system are denied by de‐
1488 fault. The container_manage_cgroup boolean must be enabled for this to
1489 be allowed on an SELinux separated system.
1490 setsebool -P container_manage_cgroup true
1493 --timeout=seconds
1496 Maximum time a container is allowed to run before conmon sends it the
1497 kill signal. By default containers will run until they exit or are
1498 stopped by podman stop.
1499 --tls-verify
1502 Require HTTPS and verify certificates when contacting registries (de‐
1503 fault: true). If explicitly set to true, then TLS verification will be
1504 used. If set to false, then TLS verification will not be used. If not
1505 specified, TLS verification will be used unless the target registry is
1506 listed as an insecure registry in registries.conf.
1507 --tmpfs=fs
1510 Create a tmpfs mount
1511 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1514 ple:
1515 $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1518 This command mounts a tmpfs at /tmp within the container. The supported
1521 mount options are the same as the Linux default mount flags. If you do
1522 not specify any options, the systems uses the following options:
1523 rw,noexec,nosuid,nodev.
1524 --tty, -t
1527 Allocate a pseudo-TTY. The default is false.
1528 When set to true Podman will allocate a pseudo-tty and attach to the
1531 standard input of the container. This can be used, for example, to run
1532 a throwaway interactive shell. The default is false.
1533 Note: The -t option is incompatible with a redirection of the Podman
1536 client standard input.
1537 --tz=timezone
1540 Set timezone in container. This flag takes area-based timezones, GMT
1541 time, as well as local, which sets the timezone in the container to
1542 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
1543 Remote connections use local containers.conf for defaults
1544 --uidmap=container_uid:from_uid:amount
1547 Run the container in a new user namespace using the supplied mapping.
1548 This option conflicts with the --userns and --subuidname options. This
1549 option provides a way to map host UIDs to container UIDs. It can be
1550 passed several times to map different ranges.
1551 The _fromuid value is based upon the user running the command, either
1554 rootful or rootless users. * rootful user: con‐
1555 tainer_uid:host_uid:amount * rootless user: container_uid:intermedi‐
1556 ate_uid:amount
1557 When podman create is called by a privileged user, the option --uidmap
1560 works as a direct mapping between host UIDs and container UIDs.
1561 host UID -> container UID
1564 The amount specifies the number of consecutive UIDs that will be
1567 mapped. If for example amount is 4 the mapping would look like:
1568 | host UID | container UID | | - | -
1571 | | _fromuid | _containeruid | | _fromuid + 1 | _containeruid +
1572 1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1573 + 3 |
1574 When podman create is called by an unprivileged user (i.e. running
1577 rootless), the value _fromuid is interpreted as an "intermediate UID".
1578 In the rootless case, host UIDs are not mapped directly to container
1579 UIDs. Instead the mapping happens over two mapping steps:
1580 host UID -> intermediate UID -> container UID
1583 The --uidmap option only influences the second mapping step.
1586 The first mapping step is derived by Podman from the contents of the
1589 file /etc/subuid and the UID of the user calling Podman.
1590 First mapping step:
1593 | host UID | intermediate UID |
1596 | - | - |
1597 | UID for the user starting Podman | 0 |
1598 | 1st subordinate UID for the user starting Podman | 1 |
1599 | 2nd subordinate UID for the user starting Podman | 2 |
1600 | 3rd subordinate UID for the user starting Podman | 3 |
1601 | nth subordinate UID for the user starting Podman | n |
1602 To be able to use intermediate UIDs greater than zero, the user needs
1605 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1606 The second mapping step is configured with --uidmap.
1609 If for example amount is 5 the second mapping step would look like:
1612 | intermediate UID | container UID | | - |
1615 - | | _fromuid | _containeruid | |
1616 _fromuid + 1 | _containeruid + 1 | | _fromuid + 2 | _con‐
1617 taineruid + 2 | | _fromuid + 3 | _containeruid + 3 | | _fromuid +
1618 4 | _containeruid + 4 |
1619 The current user ID is mapped to UID=0 in the rootless user namespace.
1622 Every additional range is added sequentially afterward:
1623 | host |rootless user namespace | length
1626 | | - | - | -
1627 | | $UID | 0 | 1
1628 | | 1 | $FIRST_RANGE_ID |
1629 $FIRST_RANGE_LENGTH | | 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID
1630 | $SECOND_RANGE_LENGTH|
1631 Even if a user does not have any subordinate UIDs in /etc/subuid,
1634 --uidmap could still be used to map the normal UID of the user to a
1635 container UID by running podman create --uidmap $container_uid:0:1
1636 --user $container_uid ....
1637 Note: the --uidmap flag cannot be called in conjunction with the --pod
1640 flag as a uidmap cannot be set on the container level when in a pod.
1641 --ulimit=option
1644 Ulimit options
1645 You can pass host to copy the current configuration from the host.
1648 --umask=umask
1651 Set the umask inside the container. Defaults to 0022. Remote connec‐
1652 tions use local containers.conf for defaults
1653 --unsetenv=env
1656 Unset default environment variables for the container. Default environ‐
1657 ment variables include variables provided natively by Podman, environ‐
1658 ment variables configured by the image, and environment variables from
1659 containers.conf.
1660 --unsetenv-all=true|false
1663 Unset all default environment variables for the container. Default en‐
1664 vironment variables include variables provided natively by Podman, en‐
1665 vironment variables configured by the image, and environment variables
1666 from containers.conf.
1667 --user, -u=user
1670 Sets the username or UID used and optionally the groupname or GID for
1671 the specified command.
1672 The following examples are all valid: --user [user | user:group | uid |
1675 uid:gid | user:gid | uid:group ]
1676 Without this argument the command will be run as root in the container.
1679 --userns=mode
1682 Set the user namespace mode for the container. It defaults to the POD‐
1683 MAN_USERNS environment variable. An empty value ("") means user name‐
1684 spaces are disabled unless an explicit mapping is set with the --uidmap
1685 and --gidmap options.
1686 Rootless user --userns=Key mappings:
1689 ┌────────┬───────────┬─────────────────────┐
1692 │Key │ Host User │ Container User │
1693 ├────────┼───────────┼─────────────────────┤
1694 │"" │ $UID │ 0 (Default User ac‐ │
1695 │ │ │ count mapped to │
1696 │ │ │ root user in con‐ │
1697 │ │ │ tainer.) │
1698 ├────────┼───────────┼─────────────────────┤
1699 │keep-id │ $UID │ $UID (Map user ac‐ │
1700 │ │ │ count to same UID │
1701 │ │ │ within container.) │
1702 ├────────┼───────────┼─────────────────────┤
1703 │auto │ $UID │ nil (Host User UID │
1704 │ │ │ is not mapped into │
1705 │ │ │ container.) │
1706 ├────────┼───────────┼─────────────────────┤
1707 │nomap │ $UID │ nil (Host User UID │
1708 │ │ │ is not mapped into │
1709 │ │ │ container.) │
1710 └────────┴───────────┴─────────────────────┘
1711 Valid mode values are:
1713 auto[:OPTIONS,...]: automatically create a unique user namespace.
1716 The --userns=auto flag, requires that the user name containers and a
1719 range of subordinate user ids that the Podman container is allowed to
1720 use be specified in the /etc/subuid and /etc/subgid files.
1721 Example: containers:2147483647:2147483648.
1724 Podman allocates unique ranges of UIDs and GIDs from the containers
1727 subordinate user ids. The size of the ranges is based on the number of
1728 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1729 den with the size option. The auto options currently does not work in
1730 rootless mode
1731 Valid auto options:
1734 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1737 to be present in the user namespace.
1738 • size=SIZE: to specify an explicit size for the automatic user
1740 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1741 fied, auto will estimate a size for the user namespace.
1742 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1744 to be present in the user namespace.
1745 container:id: join the user namespace of the specified container.
1749 host: run in the user namespace of the caller. The processes running in
1752 the container will have the same privileges on the host as any other
1753 process launched by the calling user (default).
1754 keep-id: creates a user namespace where the current rootless user's
1757 UID:GID are mapped to the same values in the container. This option is
1758 ignored for containers created by the root user.
1759 nomap: creates a user namespace where the current rootless user's
1762 UID:GID are not mapped into the container. This option is ignored for
1763 containers created by the root user.
1764 ns:namespace: run the container in the given existing user namespace.
1767 private: create a new namespace for the container.
1770 This option is incompatible with --gidmap, --uidmap, --subuidname and
1773 --subgidname.
1774 --uts=mode
1777 Set the UTS namespace mode for the container. The following values are
1778 supported:
1779 • host: use the host's UTS namespace inside the container.
1782 • private: create a new namespace for the container (default).
1784 • ns:[path]: run the container in the given existing UTS name‐
1786 space.
1787 • container:[container]: join the UTS namespace of the specified
1789 container.
1790 --variant=VARIANT
1794 Use VARIANT instead of the default architecture variant of the con‐
1795 tainer image. Some images can use multiple variants of the arm archi‐
1796 tectures, such as arm/v5 and arm/v7.
1797 --volume, -v[=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
1800 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Pod‐
1801 man bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Podman
1802 container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR will mount the
1803 volume in the host to the container. If no such named volume exists,
1804 Podman will create one. The OPTIONS are a comma-separated list and can
1805 be: [1] ⟨#Footnote1⟩ (Note when using the remote client, including Mac
1806 and Windows (excluding WSL2) machines, the volumes will be mounted from
1807 the remote server, not necessarily the client machine.)
1808 The options is a comma-separated list and can be:
1811 • rw|ro
1814 • z|Z
1816 • [r]shared|[r]slave|[r]private[r]unbindable
1818 • [r]bind
1820 • [no]exec
1822 • [no]dev
1824 • [no]suid
1826 • [O]
1828 • [U]
1830 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
1834 ume will be mounted into the container at this directory.
1835 Volumes may specify a source as well, as either a directory on the host
1838 or the name of a named volume. If no source is given, the volume will
1839 be created as an anonymously named volume with a randomly generated
1840 name, and will be removed when the container is removed via the --rm
1841 flag or podman rm --volumes.
1842 If a volume source is specified, it must be a path on the host or the
1845 name of a named volume. Host paths are allowed to be absolute or rela‐
1846 tive; relative paths are resolved relative to the directory Podman is
1847 run in. If the source does not exist, Podman will return an error.
1848 Users must pre-create the source files or directories.
1849 Any source that does not begin with a . or / will be treated as the
1852 name of a named volume. If a volume with that name does not exist, it
1853 will be created. Volumes created with names are not anonymous, and
1854 they are not removed by the --rm option and the podman rm --volumes
1855 command.
1856 You can specify multiple -v options to mount one or more volumes into
1859 a container.
1860 Write Protected Volume Mounts
1863 You can add :ro or :rw suffix to a volume to mount it read-only or
1866 read-write mode, respectively. By default, the volumes are mounted
1867 read-write. See examples.
1868 Chowning Volume Mounts
1871 By default, Podman does not change the owner and group of source volume
1874 directories mounted into containers. If a container is created in a new
1875 user namespace, the UID and GID in the container may correspond to an‐
1876 other UID and GID on the host.
1877 The :U suffix tells Podman to use the correct host UID and GID based on
1880 the UID and GID within the container, to change recursively the owner
1881 and group of the source volume.
1882 Warning use with caution since this will modify the host filesystem.
1885 Labeling Volume Mounts
1888 Labeling systems like SELinux require that proper labels are placed on
1891 volume content mounted into a container. Without a label, the security
1892 system might prevent the processes running inside the container from
1893 using the content. By default, Podman does not change the labels set by
1894 the OS.
1895 To change a label in the container context, you can add either of two
1898 suffixes :z or :Z to the volume mount. These suffixes tell Podman to
1899 relabel file objects on the shared volumes. The z option tells Podman
1900 that two containers share the volume content. As a result, Podman la‐
1901 bels the content with a shared content label. Shared volume labels al‐
1902 low all containers to read/write content. The Z option tells Podman to
1903 label the content with a private unshared label. Only the current con‐
1904 tainer can use a private volume.
1905 Note: Do not relabel system files and directories. Relabeling system
1908 content might cause other confined services on your machine to fail.
1909 For these types of containers we recommend disabling SELinux separa‐
1910 tion. The option --security-opt label=disable disables SELinux separa‐
1911 tion for containers used in the build. For example if a user wanted to
1912 volume mount their entire home directory into a container, they need to
1913 disable SELinux separation.
1914 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
1917 Overlay Volume Mounts
1921 The :O flag tells Podman to mount the directory from the host as a tem‐
1924 porary storage using the overlay file system. The container processes
1925 can modify content within the mountpoint which is stored in the con‐
1926 tainer storage in a separate directory. In overlay terms, the source
1927 directory will be the lower, and the container storage directory will
1928 be the upper. Modifications to the mount point are destroyed when the
1929 container finishes executing, similar to a tmpfs mount point being un‐
1930 mounted.
1931 Subsequent executions of the container will see the original source di‐
1934 rectory content, any changes from previous container executions no
1935 longer exist.
1936 One use case of the overlay mount is sharing the package cache from the
1939 host into the container to allow speeding up builds.
1940 Note:
1943 - The `O` flag conflicts with other options listed above.
1946 Content mounted into the container is labeled with the private label.
1950 On SELinux systems, labels in the source directory must be read‐
1951 able by the container label. Usually containers can read/execute con‐
1952 tainer_share_t and can read/write container_file_t. If you cannot
1953 change the labels on a source volume, SELinux container separation must
1954 be disabled for the container to work.
1955 - The source directory mounted into the container with an overlay
1956 mount should not be modified, it can cause unexpected failures. It is
1957 recommended that you do not modify the directory until the container
1958 finishes running.
1959 Mounts propagation
1962 By default bind mounted volumes are private. That means any mounts done
1965 inside container will not be visible on host and vice versa. One can
1966 change this behavior by specifying a volume mount propagation property.
1967 Making a volume shared mounts done under that volume inside container
1968 will be visible on host and vice versa. Making a volume slave enables
1969 only one way mount propagation and that is mounts done on host under
1970 that volume will be visible inside container but not the other way
1971 around. [1] ⟨#Footnote1⟩
1972 To control mount propagation property of a volume one can use the
1975 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
1976 For mount propagation to work the source mount point (the mount point
1977 where source dir is mounted on) has to have the right propagation prop‐
1978 erties. For shared volumes, the source mount point has to be shared.
1979 And for slave volumes, the source mount point has to be either shared
1980 or slave. [1] ⟨#Footnote1⟩
1981 If you want to recursively mount a volume and all of its submounts into
1984 a container, then you can use the rbind option. By default the bind op‐
1985 tion is used, and submounts of the source directory will not be mounted
1986 into the container.
1987 Mounting the volume with the nosuid options means that SUID applica‐
1990 tions on the volume will not be able to change their privilege. By de‐
1991 fault volumes are mounted with nosuid.
1992 Mounting the volume with the noexec option means that no executables on
1995 the volume will be able to be executed within the container.
1996 Mounting the volume with the nodev option means that no devices on the
1999 volume will be able to be used by processes within the container. By
2000 default volumes are mounted with nodev.
2001 If the <source-dir> is a mount point, then "dev", "suid", and "exec"
2004 options are ignored by the kernel.
2005 Use df <source-dir> to figure out the source mount and then use findmnt
2008 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
2009 properties of source mount. If findmnt utility is not available, then
2010 one can look at mount entry for source mount point in
2011 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
2012 tion properties are specified. shared:X means mount is shared, mas‐
2013 ter:X means mount is slave and if nothing is there that means mount is
2014 private. [1] ⟨#Footnote1⟩
2015 To change propagation properties of a mount point use mount command.
2018 For example, if one wants to bind mount source directory /foo one can
2019 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
2020 This will convert /foo into a shared mount point. Alternatively one can
2021 directly change propagation properties of source mount. Say / is source
2022 mount for /foo, then use mount --make-shared / to convert / into a
2023 shared mount.
2024 Note: if the user only has access rights via a group, accessing the
2027 volume from inside a rootless container will fail. Use the --group-add
2028 keep-groups flag to pass the user's supplementary group access into the
2029 container.
2030 --volumes-from[=CONTAINER[:OPTIONS]]
2033 Mount volumes from the specified container(s). Used to share volumes
2034 between containers. The options is a comma-separated list with the fol‐
2035 lowing available elements:
2036 • rw|ro
2039 • z
2041 Mounts already mounted volumes from a source container onto another
2045 container. You must supply the source's container-id or container-name.
2046 To share a volume, use the --volumes-from option when running the tar‐
2047 get container. You can share volumes even if the source container is
2048 not running.
2049 By default, Podman mounts the volumes in the same mode (read-write or
2052 read-only) as it is mounted in the source container. You can change
2053 this by adding a ro or rw option.
2054 Labeling systems like SELinux require that proper labels are placed on
2057 volume content mounted into a container. Without a label, the security
2058 system might prevent the processes running inside the container from
2059 using the content. By default, Podman does not change the labels set by
2060 the OS.
2061 To change a label in the container context, you can add z to the volume
2064 mount. This suffix tells Podman to relabel file objects on the shared
2065 volumes. The z option tells Podman that two containers share the volume
2066 content. As a result, Podman labels the content with a shared content
2067 label. Shared volume labels allow all containers to read/write content.
2068 If the location of the volume from the source container overlaps with
2071 data residing on a target container, then the volume hides that data on
2072 the target.
2073 --workdir, -w=dir
2076 Working directory inside the container
2077 The default working directory for running binaries within a container
2080 is the root directory (/). The image developer can set a different de‐
2081 fault with the WORKDIR instruction. The operator can override the work‐
2082 ing directory by using the -w option.
2083
2086 Create a container using a local image
2087 $ podman create alpine ls
2088 Create a container using a local image and annotate it
2092 $ podman create --annotation HELLO=WORLD alpine ls
2093 Create a container using a local image, allocating a pseudo-TTY, keeping
2097 stdin open and name it myctr
2098 podman create -t -i --name myctr alpine ls
2099 Set UID/GID mapping in a new user namespace
2103 Running a container in a new user namespace requires a mapping of the
2104 uids and gids from the host.
2105 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2108 Setting automatic user namespace separated containers
2112 # podman create --userns=auto:size=65536 ubi8-init
2113 Configure timezone in a container
2117 $ podman create --tz=local alpine date
2118 $ podman create --tz=Asia/Shanghai alpine date
2119 $ podman create --tz=US/Eastern alpine date
2120 Adding dependency containers
2124 Podman will make sure the first container, container1, is running be‐
2125 fore the second container (container2) is started.
2126 $ podman create --name container1 -t -i fedora bash
2129 $ podman create --name container2 --requires container1 -t -i fedora bash
2130 $ podman start --attach container2
2131 Multiple containers can be required.
2135 $ podman create --name container1 -t -i fedora bash
2138 $ podman create --name container2 -t -i fedora bash
2139 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2140 $ podman start --attach container3
2141 Configure keep supplemental groups for access to volume
2145 $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2146 Configure execution domain for containers using personality flag
2150 $ podman create --name container1 --personaity=LINUX32 fedora bash
2151 Create a container with external rootfs mounted as an overlay
2155 $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2156 Create a container connected to two networks (called net1 and net2) with a
2160 static ip
2161 $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2162 Rootless Containers
2166 Podman runs as a non-root user on most systems. This feature requires
2167 that a new enough version of shadow-utils be installed. The shadow-
2168 utils package must include the newuidmap and newgidmap executables.
2169 In order for users to run rootless, there must be an entry for their
2172 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2173 user namespace.
2174 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2177 packages are installed. The fuse-overlayfs package provides a
2178 userspace overlay storage driver, otherwise users need to use the vfs
2179 storage driver, which is diskspace expensive and does not perform well.
2180 slirp4netns is required for VPN, without it containers need to be run
2181 with the --network=host flag.
2182
2185 Environment variables within containers can be set using multiple dif‐
2186 ferent options: This section describes the precedence.
2187 Precedence order (later entries override earlier entries):
2190 • --env-host : Host environment of the process executing Podman
2193 is added.
2194 • --http-proxy: By default, several environment variables will
2196 be passed in from the host, such as http_proxy and no_proxy.
2197 See --http-proxy for details.
2198 • Container image : Any environment variables specified in the
2200 container image.
2201 • --env-file : Any environment variables specified via env-
2203 files. If multiple files specified, then they override each
2204 other in order of entry.
2205 • --env : Any environment variables specified will override pre‐
2207 vious settings.
2208 Create containers and set the environment ending with a * and a *****
2212 $ export ENV1=a
2215 $ podman create --name ctr --env ENV* alpine printenv ENV1
2216 $ podman start --attach ctr
2217 a
2218 $ podman create --name ctr --env ENV*****=b alpine printenv ENV*****
2220 $ podman start --attach ctr
2221 b
2222
2226 When Podman starts a container it actually executes the conmon program,
2227 which then executes the OCI Runtime. Conmon is the container monitor.
2228 It is a small program whose job is to watch the primary process of the
2229 container, and if the container dies, save the exit code. It also
2230 holds open the tty of the container, so that it can be attached to
2231 later. This is what allows Podman to run in detached mode (back‐
2232 grounded), so Podman can exit but conmon continues to run. Each con‐
2233 tainer has their own instance of conmon. Conmon waits for the container
2234 to exit, gathers and saves the exit code, and then launches a Podman
2235 process to complete the container cleanup, by shutting down the network
2236 and storage. For more information on conmon, please reference the
2237 conmon(8) man page.
2238
2241 /etc/subuid /etc/subgid
2242 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2245 age location of downloaded container images. Podman defaults to use
2246 /var/tmp.
2247
2250 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2251 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
2252 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
2253 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
2254 slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2255
2258 October 2017, converted from Docker documentation to Podman by Dan
2259 Walsh for Podman <dwalsh@redhat.com>
2260 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2263 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2266 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2269
2272 1: The Podman project is committed to inclusivity, a core value of open
2273 source. The master and slave mount propagation terminology used here is
2274 problematic and divisive, and should be changed. However, these terms
2275 are currently used within the Linux kernel and must be used as-is at
2276 this time. When the kernel maintainers rectify this usage, Podman will
2277 follow suit immediately.
2278 podman-create(1)()