Images and Containers
Search for images with a keyword:
$ podman search fedora $ podman search homeassistant
The registries which will be searched are configured in the /etc/containers/registry.conf file.
The search result will include both the registry location and the name of the image.
The registry name may include a port number.
The image name consists of USER/REPO. The user can be an individual, team, or company that uploads the images to the registry.
The image repository contains tagged images and hidden layers. Most repositories contain an image with the tag of 'latest'.
When downloading an image with pull, run, or build commands, you may specify a specific tag image. The default is to pull the image tagged 'latest'.
skopeo command is a utility to work with images in many different container environments.
It was created to view information in remote registries and is now a command and library for copying images with different transports.
It is used to manage container images and image storage remotely and locally and all without requiring root.
It can also pass authentication credentials when required by the repository.
View creation dates, architectures, labels, tags, and layer checksums of a remote image repository:
$ skopeo inspect docker://registry.fedoraproject.org/fedora-minimal
Manage Local Images
When you run a container, the image is first downloaded to the local system. It can be helpful to go ahead and download an image as a separate command.
The default is to pull the latest image from the default registry:
$ podman pull fedora
You can also specify the registry, user, tag, or, as in the following example, some combination:
$ podman pull registry.fedoraproject.org/fedora-minimal:rawhide
List the local images:
$ podman images REPOSITORY TAG IMAGE ID CREATED SIZE registry.fedoraproject.org/fedora-minimal rawhide 8ecda3b9bc0d 2 days ago 164MB docker.io/homeassistant/raspberrypi3-homeassistant latest 3c74046ca2a7 3 days ago 1.05GB docker.io/library/fedora latest 8b38e3af7237 4 weeks ago 315MB
The same output is show with
podman image ls.
Note the singular 'image' command before the additional 'ls' command.
If you have a lot of images, you may want to specify filters or sort by a value other than the creation date.
As a user, the local images will be stored under the
Each user has their own namespace so these are separate from containers run as root.
Listing the images available to root displays a different or empty list:
$ sudo podman images
Some actions can not be done with rootless containers. Some devices and volumes will require that you pull and run containers in the root namespace. The current podman v1.0 also requires root for port publishing. The next version will allow rootless port publishing.
Like remote images, local images can also be inspected:
$ podman inspect fedora
To inspect an image with a tag other than 'latest', include the tag:
$ podman inspect fedora-minimal:rawhide
To launch the container use:
$ podman run fedora
With the fedora image, the container will start and then it exits since there is nothing left running. Some images are configured to run an application in the foreground and the container will not terminate until the application terminates.
To list the running containers use:
$ podman container ls
To see all containers, including those that have exited:
$ podman container ls -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES IS INFRA 7835aaadd2d1 docker.io/library/fedora:latest /bin/bash About a minute ago Exited (0) 14 seconds ago hopeful_beaver false
The exited containers are kept so that any data, including logs, can be investigated before they are lost. You can start an exited container but a typical workflow normally deletes used containers, launching new containers when needed.
Options on the run command can change the behavior of launching a container:
$ podman run -it \ (1) > --name demo \ (2) > --rm \ (3) > fedora /bin/bash (4) bash-4.4# (5)
|1||The -it options enable interactive mode and allocates a pseudo-TTY.|
|2||You can name your container. Without this option, a random name will be generated.|
|3||The --rm option causes the container to be deleted when it is terminated. This preserves space and allows a new container to be started with the same name.|
|4||The command to run. The command must be in the image. Not all images include bash.|
|5||The /bin/bash process is running in the foreground. When you exit the shell, the container will terminate.|
If your application listens on the network, you will need to map the container port to a local port on your device. In the current version, publishing ports requires root so the image must be available in the root namespace.
-p option when you launch the container:
$ sudo podman run -p 127.0.0.1:8080:80 --name demo mydemohttp:latest
You can then connect to your application via 127.0.0.1:8080
The format is
ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort.
Other options for publishing ports and many other run options are available and well documented in the podman-run man page.
Mapping a local directory
You may want to have your application write logs or collect data to a directory on the host.
Some containers expect that customized configuration files are on the host device.
In both cases, you can create a bind mount with the
Specify the host directory, the mount point inside the container, and any mount options.
For example, Home Assistant expects the configuration files to be on the host device:
$ podman run -d --name="home-assistant" -v /home/pi/homeassistant:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/raspberrypi3-homeassistant
Mapping a local device
--device option will add a host device to the container.
Specify the host device name and optionally, the device name on the container and any permissions.
Some devices, like the GPIO device, will require root.
To access the host GPIO device from the container:
$ sudo podman run -it --rm --name demo-gpio --device=/dev/gpiochip0 fedora:latest /bin/bash
Connect to a Running Container
You can also connect to a running container. Specify the container name or ID and the command to execute:
$ podman exec -it demo /bin/bash
You can also view container logs directly with podman:
$ podman logs demo
logs commands are also part of the
podman container command.
Removing Containers and Images
List the containers to see the 'Container ID' and 'name' of each container. Remove a container by specifying either the container ID or name:
$ podman container rm demo
Removing a container happens automatically when a container terminates if the container was started with the
Removing a container does not remove the image.
List the local images with
podman images or
podman image ls.
Remove the image using either the 'IMAGE ID' or the repository name and tag:
$ podman rmi registry.fedoraproject.org/fedora-minimal:rawhide
You can also remove an image with the
$ podman image rm registry.fedoraproject.org/fedora-minimal:rawhide
Want to help? Learn how to contribute to Fedora Docs ›