Podman commands

Podman command lines from the synopsis and EXAMPLES sections of the Podman 6.1.3 man pages, grouped by task from running containers to rootless and systemd use. The command line is modelled on Docker's, so podman run and podman ps behave as a Docker user expects. On macOS and Windows a virtual machine must be running first: podman machine start. Example names such as mywebserver come from the man pages; checkpointing, image trust and manifest editing are left out.

187 commands in 11 sections. Checked row by row against Podman 6.1.3 man page: podman(1) on . Edited by Jay.

Running containers 15

The podman(1) page describes the command line as comparable to Docker's and sums it up as alias docker=podman. It adds that most commands run as a regular user, with no extra privileges.

CommandWhat it does
podman runCreate and start a containerPulls the image first when it is not in local storage, then starts the command in a fresh container.
podman run registry.fedoraproject.org/fedora:latest echo helloRun one command from a registry imageThe image reference comes first, then the command and its arguments.
podman run -p 8080:80 -d fedora/httpdRun detached with a published portMaps host port 8080 to port 80 in the container and returns the prompt while it keeps running.
podman run -ti --rm -e TZ=EST mytzimageRun once with an environment variable-e sets a variable inside the container, and --rm deletes the container when it exits.
podman run --read-only -i -t fedora /bin/bashRun with a read-only root filesystemThe image content cannot be modified, while temporary data stays writable by default.
podman run -v /var/db:/data1 -i -t fedora bashMount a host directoryWrite the absolute host path, a colon, then the absolute path inside the container.
podman run -v data:/data2 -i -t fedora bashMount a named volumeRefer to a Podman-managed volume by its name, or volume prune treats it as an orphan.
podman run --mount type=bind,src=/etc/config,dst=/app/config alpine cat /app/config/file.confBind mount with --mountLinks a host file or directory into the container; a change on one side shows up on the other at once.
podman run --mount type=volume,src=mydata,dst=/var/lib/data postgresMount a volume with --mountUses a named volume that outlives the container, which suits database files and logs.
podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addrJoin two networks with fixed addressesRepeat --network once per network; the ip= suffix sets a static address on each.
podman createCreate a container without starting itPrints the new container ID; the container stays in the created state until podman start runs it.
podman create -t -i --name myctr alpine lsCreate a named interactive containerReserves a terminal, leaves standard input open and calls the container myctr.
podman secretSecret subcommand groupSecrets carry sensitive data such as passwords or keys that containers need at run time.
podman secret create my_secret ./secret.txtCreate a secret from a fileWrite - in place of the file name to read the secret from standard input.
podman run --rm --secret source=my_secret,type=mount,uid=1001,gid=1001,mode=440 docker.io/library/alpine ls -l /run/secrets/my_secretMount a secret in a containerThe secret shows up as a file under /run/secrets with the owner and mode given.

Starting, stopping and removing containers 18

Many container commands accept --latest (-l) to act on the last created container, but not through the remote client, which is what macOS and Windows machines use (WSL2 excepted).

CommandWhat it does
podman startStart existing containersTakes names or IDs; the terminal and interactive settings chosen at creation cannot be changed here.
podman start --attach container2Start and attach to outputConnects the terminal to STDOUT and STDERR; only one container can be started this way.
podman stopStop running containersSends SIGTERM, then SIGKILL after a timeout that defaults to 10 seconds.
podman stop -aStop every running containerPaused containers are left as they are.
podman stop --time 2 860a4b235279Stop with a custom timeoutWaits two seconds before stopping the container by force; -1 waits without limit.
podman restartRestart containersRunning containers are stopped and started again; stopped ones are simply started.
podman rmRemove containersImages are kept, and a running container is only removed when -f is added.
podman rm -f 860a4b23Force-remove a containerWith -f a running or paused container is removed as well.
podman rm -f -aRemove every containerDeletes all containers whether they are running or not.
podman container pruneDelete all stopped containersAsks for confirmation unless -f is given; --filter narrows what is removed.
podman killSignal a container's main processSIGKILL is sent unless --signal names another signal.
podman pauseFreeze container processesSuspends every process in the listed containers until podman unpause is run.
podman unpauseResume paused containersLets the processes of paused containers continue; --all resumes every paused container.
podman waitBlock until containers stopPrints the exit code of each container once it has stopped, in the order given.
podman renameRename a containerWorks in any state, though a running container may keep the old name in its logs until restarted.
podman updateChange container resource limitsAdjusts resource limits and healthcheck settings of a container that already exists.
podman initPrepare containers without startingMounts filesystems and writes the OCI spec so both can be examined before the container starts.
podman containerContainer subcommand groupHolds the long forms of the container commands plus extras such as checkpoint, clone, exists and prune.

Listing, logs and inspection 28

CommandWhat it does
podman psList running containersColumns show ID, image, command, creation time, status, ports and names.
podman ps -aList all containersAdds containers that are not running to the list.
podman ps -a --filter status=exitedList exited containersThe status filter also accepts states such as created, running, paused and stopped.
podman ps -a --format "{{.ID}} {{.Image}} {{.Labels}} {{.Mounts}}"Choose the output columnsA Go template picks the fields printed for each container.
podman logsShow container logsFetches what has been logged so far; add -f to keep following new output.
podman logs --tail 2 b3f2436bdb97Show the last log linesThe number says how many lines from the end of the log to print.
podman logs -t --since 0 myserverShow all logs with timestamps-t puts the time of each entry in front of its line.
podman logs --since 10m myserverShow recent log entriesAccepts a Go duration such as 10m, a Unix timestamp or a date.
podman execRun a command in a containerThe target container must already be running.
podman exec -it ctrID lsRun a command with a terminal-i keeps standard input open and -t gives the command a pseudo-terminal.
podman exec --user root ctrID lsRun a command as another userWithout --user the command runs as the user set in the image.
podman exec -d ctrID find /path/to/search -name yourfileRun a command in the backgroundPrints the exec session ID and returns at once; the session is removed when the command finishes.
podman attachConnect to a container's streamsThe default detach sequence is Ctrl + P, Ctrl + Q, which leaves the container running.
podman cpCopy files to or from a containerCopies between host and container or between two containers, whether they are running or stopped.
podman cp /myapp/app.conf containerID:/myapp/app.confCopy a host file into a containerThe container side is written as the container name or ID, a colon, then the path.
podman cp containerID1:/myfile.txt containerID2:/tmpCopy between two containers
podman inspectShow low-level configurationReturns a JSON array for containers, images, volumes, networks, pods or artifacts found by name or ID.
podman inspect a04 --format "{{.ImageName}}"Print one field of an objectA Go template selects which keys of the JSON are printed.
podman statsStream resource usageUpdates live for running containers; rootless mode cannot report network usage.
podman stats -a --no-streamPrint one usage snapshot-a covers every container and --no-stream prints a single result, then exits.
podman topList processes in a containerOutput resembles ps -ef unless format descriptors follow the container name.
podman portShow port mappingsLists every mapping of a container, or looks up the host port behind one private port.
podman port b4d2f054 80/tcpLook up one mapped port
podman diffShow filesystem changesEach path is marked A for added, D for deleted or C for changed.
podman mountMount a container's filesystemReturns the host path; with no arguments it lists the containers mounted now.
podman unmountUnmount a container's filesystempodman umount is the same command; the filesystem is released only when its mount counter reaches zero.
podman healthcheckHealthcheck subcommand groupChecks usually come from the image or from --health-cmd options given to run or create.
podman healthcheck run mywebappRun a healthcheck nowExit code 0 means the check passed, 1 that it failed and 125 that an error occurred.

Images and registries 32

CommandWhat it does
podman imagesList local imagespodman image ls and podman image list are the same command.
podman images --filter dangling=trueList untagged imagesShows only dangling images, the ones that carry no name.
podman imageImage subcommand groupLong forms such as podman image ls sit here, next to image-only commands like prune, tree and scp.
podman pullDownload an imageA short name without a registry is resolved through an alias or a prompt for the registry to use.
podman pull alpine:latestPull by short name and tag
podman pull alpine@sha256:d7342993700f8cd7aba8496c2d0e57be0666e80b4c441925fc6f9361fa81d10ePull by digest
podman pull --arch=arm arm32v7/debian:stretchPull for another architectureLater lookups of this image in local storage then match that architecture, whatever the host is.
podman pushUpload an imageWithout a transport prefix the destination is a container registry; dir:, oci-archive: and others are accepted.
podman push myimage quay.io/username/myimagePush under another nameThe second argument is the destination, so the local name need not match the remote one.
podman tagAdd a name to an imageWhen no tag is written, latest is assumed for both the image and the new name.
podman tag httpd myregistryhost:5000/fedora/httpd:v2Tag for a private registryThe full name carries the registry host, port, repository and tag.
podman untagRemove names from an imageWith no name given, every name is removed from the image.
podman rmiDelete local imagesDangling parent images are deleted as well; images in a remote registry are not affected.
podman rmi --force imageIDForce-remove an image in useContainers that use the image are removed first.
podman rmi -a -fDelete every imageThe containers using those images are removed along with them.
podman historyShow image layer historyLists each layer with its creation time, the instruction that made it, its size and comment.
podman searchSearch registries for an imageReturns up to 25 results per registry by default; prefix the term with a registry to search only there.
podman search --limit 3 fedoraLimit the number of resultsThe limit applies to each registry searched, not to the total.
podman search --list-tags registry.access.redhat.com/ubi8 --limit 4List tags of a repositoryNeeds a fully specified image name and prints one line per tag.
podman loginLog in to a registryPrompts for a username and password unless options supply them.
podman login quay.ioLog in to one registryCredentials go under $XDG_RUNTIME_DIR by default, so they do not survive a reboot.
podman login -u testuser --password-stdin < testpassword.txt docker.ioRead the password from standard inputKeeps the password out of the command line by taking it from a file or pipe.
podman logoutLog out of a registryDeletes the cached credentials for that registry from the auth.json file.
podman logout --allLog out of every registry
podman saveSave an image to an archiveWrites to standard output unless -o names a file; podman load restores the result.
podman save -o oci-alpine.tar --format oci-archive alpineSave as an OCI archiveThe default format is docker-archive, which docker load can read.
podman loadLoad images from an archiveReads standard input by default; -i takes a tar file, a directory or a URL.
podman load --quiet -i fedora.tar.gzLoad a compressed tar file--quiet hides the progress output while the archive is read.
podman importImport a tarball as an imageMeant for archives made by podman export; the tarball may be compressed or given as a URL.
podman exportExport a container's filesystemFlattens the filesystem into one tarball, written to standard output unless -o names a file.
podman commitCreate an image from a containerThe container is paused while the image is written unless --pause=false is given.
podman artifactOCI artifact subcommand groupPulls, inspects and pushes OCI artifacts, files distributed alongside images, kept in a local artifact store.

Building images 10

CommandWhat it does
podman buildBuild an imageLooks for a file named Containerfile or Dockerfile in the context directory unless -f names another.
podman build .Build from the current directoryThe dot makes the current directory the build context.
podman build -t imageName .Build and name the imageA name without a registry gets localhost put in front.
podman build -f Containerfile.simple .Build from a named Containerfile-f accepts a local file or an http(s) URL and can be given more than once.
podman build --no-cache --rm=false -t imageName .Build without the cacheStarts from scratch with new layers and keeps the intermediate containers afterwards.
podman build --secret=id=mysecret,src=.mysecret .Pass a build secret from a fileRUN instructions can read the secret, but it does not end up in the final image.
podman build --platform linux/arm64 --platform linux/amd64 --manifest myimage /tmp/mysrcBuild for several platformsEach platform image is added to the manifest list myimage, which is created when missing.
podman build -t hello https://github.com/containers/PodmanHello.gitBuild from a Git repositoryThe repository is fetched to a temporary location and used as the build context.
podman manifestWork with manifest listsSubcommands create, extend, inspect and push manifest lists and image indexes for multi-arch images.
podman farmDistribute builds to other machinesBuilds for other architectures run on remote Podman machines, which need version 4.9.0 or newer.

Volumes 10

CommandWhat it does
podman volumeVolume subcommand groupParent command for creating, listing, inspecting, pruning and removing volumes.
podman volume createCreate a volumeA random name is generated when none is given.
podman volume create myvolCreate a named volume
podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=size=2M,nodev,noexec myvolCreate a tmpfs volumeWith the local driver, the type, device and o options are handed on to mount.
podman volume lsList volumes--format json or a Go template changes the output; --quiet prints only the names.
podman volume inspect myvolInspect a volumeA unique part of the name is enough to identify the volume.
podman volume rm myvol1 myvol2Remove volumesA volume still used by a container is refused unless --force is added.
podman volume rm --force myvolRemove a volume in useThe containers using the volume are removed first.
podman volume pruneRemove unused volumesOnly anonymous volumes go by default, after a confirmation prompt.
podman volume prune --all --forcePrune named volumes tooRemoves every unused volume, named or anonymous, without asking.

Networks 12

CommandWhat it does
podman networkNetwork subcommand groupNetavark is the backend behind the networks these subcommands manage.
podman network createCreate a networkWith no options Podman picks a free subnet and a name and makes a bridge network.
podman network create --subnet 192.5.0.0/16 newnetCreate a network with a subnetThe subnet is written in CIDR notation; repeat the option to give the network several subnets.
podman network create -d macvlan -o parent=eth0 --subnet 192.5.0.0/16 newnetCreate a macvlan networkUses host interface eth0 as the parent device and has to be run with root rights.
podman network lsList networks
podman network inspect podmanInspect the default networkThe default network is called podman; its configuration is printed as JSON.
podman network rm podman9Remove a network
podman network rm -f fredRemove a network in useStops and removes the containers that use the network first.
podman network connect test webConnect a container to a networkThe network name comes first, then the container, here test and web.
podman network connect --ip 10.89.1.13 test webConnect with a static IP
podman network disconnect test webDisconnect a containerWith no network left, the container has no connectivity until one is connected again.
podman network pruneRemove unused networksDeletes networks with no containers attached, except the default network named podman.

Pods, Kubernetes YAML and Compose 22

CommandWhat it does
podman podPod subcommand groupA pod is a group of containers managed together.
podman pod createCreate an empty podPrints the pod ID; containers join later through the --pod option of create or run.
podman pod create mypodCreate a named pod
podman pod create --publish 8443:443Publish a port for the podHost port 8443 is mapped to port 443 inside the pod.
podman create --pod mypod nginxAdd a container to a podCreates the container inside the existing pod named mypod.
podman ps --podShow the pod of each containerExtends the container list with the pod each one is associated with.
podman pod psList podsShows each pod with its ID, name, status, creation time and number of containers.
podman pod start mywebserverpodStart a podStarts the containers in the pod, which needs at least one container attached.
podman pod stop mywebserverpodStop a podStops the containers in the pod; -t sets how many seconds to wait before forcing them.
podman pod rm mywebserverpodRemove a stopped podRemoves the pod together with its containers once they have all exited.
podman pod rm -f -aForce-remove all podsRunning containers are stopped first, then pods and containers are deleted.
podman pod inspect foobarInspect a pod
podman pod logs -c ctrIdOrName podIdOrNameShow logs of one pod containerWithout -c the logs of all containers in the pod are printed.
podman kubeKubernetes YAML subcommand groupMeant for moving workloads between Podman and Kubernetes; it does not replicate kubectl.
podman kube play demo.ymlCreate pods from Kubernetes YAMLRecreates the pods, containers and volumes in the file and starts the containers.
podman kube play --down https://podman.io/demo.ymlTear down what a play created--down removes the pods made by an earlier play of the same YAML.
podman kube generate some-mariadbGenerate Kubernetes YAMLPrints a Pod specification by default, whether the input is a container or a pod.
podman kube generate --type deployment --replicas 3 dep-ctGenerate a Deployment--replicas is only accepted together with --type deployment.
podman kube generate -s demowebGenerate YAML with a ServiceAdds a Service object for the pod, with a NodePort when ports are mapped.
podman kube down demo.ymlRemove pods made from YAMLVolumes created by the earlier play are kept unless --force is added.
podman generateGenerate subcommand groupIts subcommands are kube, spec and the deprecated systemd.
podman composeRun a Compose providerA thin wrapper: arguments go straight to docker-compose or podman-compose, whichever is installed.

Machines on macOS and Windows 12

Every podman machine command is rootless only, so it is run as a regular user. Whether containers inside the VM run rootful is a separate machine setting (--rootful).

CommandWhat it does
podman machineManage the Podman VMRequired on macOS and Windows, where containers run inside a Linux virtual machine; optional on Linux.
podman machine initCreate the default machineThe machine is named podman-machine-default and its image is downloaded first.
podman machine init --nowCreate and start a machineSaves the separate start step after initialization.
podman machine init --rootfulCreate a rootful machineMakes rootful container execution the default for connections to this machine.
podman machine init -v /Users:/UsersShare a host directory with the VMThe host folder is mounted in the machine at the path after the colon.
podman machine startStart a machineStarts podman-machine-default when no name is given; only one managed VM can be active at a time.
podman machine stopStop a machineStops podman-machine-default when no machine name is given.
podman machine sshOpen a shell in the VMWith no command given, an interactive session with the default machine opens.
podman machine ssh myvm rpm -q podmanRun a command in a machineThe machine name must come first unless the default machine is meant.
podman machine listList machinespodman machine ls is the same command.
podman machine set --rootful myvmSwitch a machine to rootfulUseful when containers need root permissions, for example to bind ports below 1024.
podman machine rm test1Remove a machineDeletes the VM image, its ignition files and its system connections after a confirmation.

System information and cleanup 15

CommandWhat it does
podman infoShow host and storage detailsCovers the host, storage statistics, configured registries and the Podman build.
podman versionShow version detailsReports the version, API version, Go version, Git commit, build time, OS and architecture.
podman version --format '{{.Client.Version}}'Print only the client version
podman systemSystem subcommand groupHome of maintenance commands such as df, prune, reset, migrate, connection and service.
podman system dfShow disk usageSummarises space used by images, containers and volumes; the reclaimable figure for images can be too high.
podman system pruneRemove unused dataDeletes unused containers, pods, networks and dangling images; volumes are kept unless --volumes is added.
podman system prune --allPrune unused images tooAlso removes every image that no container is based on.
podman image pruneRemove dangling imagesAdd -a to delete every image that no container uses.
podman system resetWipe all Podman storageRemoves every pod, container, image, network, volume and machine, after a confirmation prompt.
podman eventsWatch Podman eventsEach event has a timestamp, type and status; journald is the default event logger.
podman events --filter event=create --filter type=podFilter eventsRepeating --filter narrows the stream, here to the creation of pods.
podman system connection listList remote connections
podman system connection add --identity ~/.ssh/dev_rsa production ssh://[email protected]:2222Add an SSH connectionRecords a remote Podman service under the name production, with the key file to use.
podman system connection default productionSet the default connection
podman system service --time 0 unix:///var/run/mypodman.sockRun the API service on a socketServes the Podman API without systemd socket activation; --time 0 turns the inactivity timeout off.

Rootless and systemd integration 13

The man page marks podman generate systemd as deprecated and recommends Quadlet files for running containers or pods under systemd. It also says there are no plans to remove the command.

CommandWhat it does
podman unshareEnter the rootless user namespaceStarts your shell by default, with your UID and GID appearing as 0 inside.
podman unshare cat /proc/self/uid_map /proc/self/gid_mapShow the UID and GID mappingsPrints the ID ranges that rootless containers of your user are mapped onto.
podman run -d -e MARIADB_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:Z,U mariadbWritable volume for a non-root userThe U option changes the owner of the source directory to the IDs the container runs with.
podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo helloMap UIDs and GIDs by handEach mapping reads container ID, host ID, then how many IDs the range covers.
podman system migrateRefresh containers after an upgradeAlso stops the pause process, which is how new /etc/subuid and /etc/subgid ranges reach rootless containers.
podman auto-updateUpdate containers run by systemdPulls newer images and restarts the systemd units of containers labelled io.containers.autoupdate.
podman auto-update --dry-run --format "{{.Image}} {{.Updated}}"Check for image updates onlyNothing is pulled or restarted; pending marks an image that has a newer version.
podman generate systemdGenerate systemd units (deprecated)Deprecated in favour of Quadlet files; it still gets urgent bug fixes but no new features.
podman generate systemd --new --files --name bb310a0780aeWrite portable unit files--new makes units that build and delete the container themselves; --files saves them in the current directory.
podman quadletQuadlet subcommand groupQuadlets describe containers, pods, volumes, networks and images as systemd unit files.
podman quadlet install test-service-quadlet.containerInstall a Quadlet fileInstalls for the current user and reloads systemd afterwards by default.
podman quadlet listList installed QuadletsCovers the Quadlets configured for the current user.
podman quadlet rm myquadlet.containerRemove an installed QuadletRemoving one Quadlet of an application removes the whole application.

Notes

The Docker-shaped core

Container lifecycle is podman run, podman ps, podman logs, podman exec and podman stop, and podman rm removes a stopped container. Images follow the same pattern with podman pull, podman images, podman build and podman rmi. The one habit to break is expecting a daemon: Podman is daemonless, and a container started in the foreground stays attached to your terminal, so start it with -d when it should keep running in the background.

What Podman has that Docker does not

podman pod groups containers that share a network namespace, the same model Kubernetes uses, and podman kube plays a Kubernetes YAML file directly — the fastest way to try a deployment manifest on a laptop. podman generate goes the other way and produces Kubernetes YAML from existing containers and pods; its systemd subcommand is deprecated in favour of Quadlet. podman quadlet manages the declarative unit files that let systemd own container lifecycle on a server. podman unshare opens a shell inside your rootless user namespace, which is how you fix file ownership on volumes that look wrong from the host.

macOS, Windows and machines

Because Podman needs a Linux kernel, podman machine creates and manages the virtual machine that runs containers on macOS and Windows. podman machine init sets it up once and podman machine start boots it; until it is running, the client has nothing to connect to. podman system holds the maintenance verbs — prune, reset, and the connection list that tells you which machine or remote host commands are going to. podman info prints the effective configuration, including whether the current session is rootless.

Questions

Can I use Docker commands with Podman?

Mostly, yes. Podman's command line is built to be comparable with Docker's, and its man page sums the idea up as alias docker=podman. Compose workloads use podman compose, which drives an external compose provider such as docker-compose or podman-compose.

Why does my container stop when I close the terminal?

A container started in the foreground is attached to that terminal, and podman run passes the signals it receives on to the container process. Run it detached (-d), or let systemd manage it with a Quadlet file; podman generate systemd still works but is deprecated.

What is a pod?

A group of containers that Podman manages as one unit and that share namespaces such as the network, like a Kubernetes pod. Create one with podman pod create and add containers with the --pod option of podman create or podman run.

Why do files in my volume have strange owner IDs?

Rootless Podman maps container UIDs into your user namespace. Use podman unshare to open a shell where the mapping is applied and fix ownership there, or mount the volume with the U option so Podman changes the owner for you.

Sources and checks

102 more source pages

Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.

Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.