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 containers

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).

More commands

  • podman inspect <element>: information about a container, image, network, etc.

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

Podman Compose

There is a package in Arch Linux official repositories called podman-compose that can run Docker Compose environments with podman. After installed, just replace docker-compose with podman-compose (e.g.: podman-compose up). In addition to that, since v3.0, Podman supports Docker Compose, which can run against Podman REST API (only when running as root).

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"]
  • Remove external containers (from interrupted builds). When a temporary container has been created by a tool like ‘buildah’ during an image creation, it will show when running podman ps --external. To remove those containers (after interrupting a build, for example), first list the containers with the above command to see their ID. Then, unmount the containers: podman unmount <container ID>. Finally, remove the container with podman rm <container ID>.

If you have any suggestion, feel free to contact me via social media or email.