Podman is a Docker-compatible command-line container manager with great features and easy to install and use.

Table of Contents

Installation

You can install podman with a package manager (apt, pacman, etc.)

Useful features

  • You don’t need to add the user to any group to be able to use Podman without sudo (rootless mode). But you maybe need root permissions for some tasks.
  • Every user has its own containers (and images).

Usage

Podman has the same commands as Docker: ps, run, images, rm, stop/start, etc. You can even create an alias if you want to type docker instead of podman:

alias docker=podman

Run containers:

podman run -it docker.io/library/archlinux

Because podman is compatible with several registries, you need to use full paths when referring to an image:

  • Official images have this path: docker.io/library/<image>.
  • Images from other publishers have this path: docker.io/<publisher>/<image>. 
    # Run
podman run -d -p 8080:6901 docker.io/accetto/ubuntu-vnc-xfce-firefox-g3
# instead of
podman run -d -p 8080:6901 accetto/ubuntu-vnc-xfce-firefox-g3

You can type debian (instead of docker.io/library/debian) because there is an alias to the full path on shortnames.conf (inside /etc/containers/). Edit this file to add more aliases.

Stop/start created containers (like shutdown/start a computer):

podman stop <container name/ID>

podman start <container name/ID>

Pause/unpause containers (like hibernating a computer, pauses processes):

podman pause <container name/ID>

podman unpause <container name/ID>

List containers:

podman ps #show running containers
podman ps -a #show stopped and running containers

Remove them:

podman rm <container ID/name>

Copy files to container:

podman cp <file> <container ID/name>:<path>

Export/import a container:

# Container example name: mycontainer
# New image example name: mynewimage
podman export -o mycontainer.tar mycontainer
podman import --change ENTRYPOINT=/bin/bash mycontainer.tar mynewimage
# You may need to change entrypoint if your container has another shell
podman run -it docker.io/library/mynewimage

Save an image locally:

podman save --format <format> -o <file> <image>
  • Available formats: docker-archive (tar archive compatible with docker load), oci-archive (tar archive using the OCI Image Format), oci-dir (a directory using the OCI Image Format), docker-dir (dir transport).

Check https://docs.podman.io/en/latest/Commands.html for more info about available commands.

Troubleshooting

  • Binary not found warning. 
    WARN[0002]  binary not found, container dns will not be enabled

    Try installing aardvark-dns.

  • newuidmap error. 
    newuidmap: subuid overflow detected

    Try editing /etc/subuid and /etc/subgid:

    root:100000:65536
<your username>:100000:65536
  • podman search <search term> does not return any results. Edit /etc/containers/registries.conf, uncomment and edit this line (by replacing example.com with docker.io): 
    unqualified-search-registries = ["docker.io"]