Podman 5 8 1

Podman 5.8.1

Overview

Podman (the POD MANager) is a daemonless, open source, Linux native tool for managing OCI containers and container images. It provides a command line interface familiar to anyone who has used Docker — most users can simply alias docker=podman without issues. Podman manages the entire container ecosystem including pods, containers, images, and volumes using the libpod library.

Key differentiators from Docker:

• No daemon — improved security and lower resource utilization at idle
• Rootless by design — containers run as normal users via user namespaces, no setuid binary required
• Pods support — groups of containers sharing resources, similar to Kubernetes pods
• Systemd integration — declarative container management via Quadlet unit files
• Remote client — manage containers on remote Linux hosts over SSH from Mac/Windows/Linux
• Kubernetes integration — kube play and kube generate for bidirectional YAML conversion

Podman uses best-of-breed OCI libraries: crun or runc for runtime, Netavark for networking, pasta for rootless networking, Buildah for image builds, and containers/storage (SQLite backend, BoltDB deprecated in 6.0) for storage.

When to Use

• Building, running, or managing OCI containers without a background daemon
• Implementing rootless container workflows where users run containers without root privileges
• Deploying container workloads on Mac or Windows via podman machine virtual machines
• Managing containers declaratively with systemd via Quadlet unit files
• Converting between Podman containers and Kubernetes YAML with kube play/kube generate
• Automating container lifecycle management in CI/CD pipelines
• Migrating from Docker to a daemonless alternative (alias docker=podman)
• Running containers remotely over SSH from any platform
• Managing OCI artifacts alongside container images
• Configuring complex container networking with Netavark and pasta

Core Concepts

Daemonless architecture: Unlike Docker, Podman has no persistent daemon. Each podman command forks a new process. Containers are managed through fork-exec, making the system more resilient — killing the podman process does not affect running containers. Conmon monitors container processes and handles cleanup.

Rootless containers: Podman runs containers as a normal user without root privileges. User namespaces map the container's root UID to the host user's UID. The administrator configures /etc/subuid and /etc/subgid to allocate UID/GID ranges per user. Rootless containers never have more privileges than the launching user.

Pods: A pod is a group of containers that share the same network namespace, IPC namespace, and optionally other resources. Pods provide a Kubernetes-like grouping without requiring a full orchestrator. The infra container manages shared resources.

Quadlet: Declarative container management using systemd unit files. Quadlet translates .container, .pod, .volume, .network, .image, and .build unit files into Podman commands, enabling containers to be managed as systemd services with automatic restart, dependencies, and lifecycle management.

Remote client: Podman on Mac and Windows connects to a Linux backend (managed VM or external server) over SSH. The podman-remote binary or podman --remote communicates with the Podman REST API exposed via podman.socket.

Installation / Setup

Podman is available on most Linux distributions via package managers (apt, dnf, yum, zypper). On Mac and Windows, install from podman.io — it includes a managed VM backend.

For rootless operation, the administrator must:

• Install pasta (rootless networking tool, package name passt)
• Configure subordinate UIDs/GIDs in /etc/subuid and /etc/subgid:

usermod --add-subuids 100000-165535 --add-subgids 100000-165535 johndoe

• Enable linger for persistent rootless socket (optional):

sudo loginctl enable-linger $USER

Configuration files are read in this order (later overrides earlier):

• /usr/share/containers/containers.conf → /etc/containers/containers.conf → $HOME/.config/containers/containers.conf
• /etc/containers/storage.conf → $HOME/.config/containers/storage.conf
• /etc/containers/registries.conf → /etc/containers/registries.d/* → $HOME/.config/containers/registries.conf

Usage Examples

Run a simple container:

podman run --rm -it alpine sh

Run with port mapping and volume mount:

podman run -d --name web -p 8080:80 -v ./data:/data nginx

Build an image from a Containerfile:

podman build -t myapp:latest .

Manage pods:

podman pod create --name mypod --port 8080:80
podman run -d --pod mypod nginx
podman run -d --pod mypod redis

Rootless container with keep-id namespace:

podman run --rm --userns=keep-id -v $PWD:/work alpine ls -la /work

Kubernetes play:

podman kube play app.yaml
podman kube down app.yaml

Advanced Topics

Rootless Containers: Detailed setup, user namespace configuration, volume semantics, and known limitations → Rootless Containers

Pods and Pod Management: Creating pods, shared namespaces, lifecycle management, pod stats → Pod Management

Networking with Netavark and Pasta: Bridge networks, pasta rootless networking, DNS, subnet pools, network options → Networking

Quadlet and Systemd Integration: Declarative container management via systemd unit files, .container, .pod, .volume units, service generation → Quadlet and Systemd

Remote Client and podman machine: Managing containers over SSH, Mac/Windows VM backends, connection configuration, libkrun/applehv providers → Remote Client and Machine

Kubernetes Integration: kube play, kube generate, kube down, bidirectional YAML conversion, CDI device support → Kubernetes Integration

Container Image Management: Building, pulling, pushing, tagging, importing, OCI artifacts, trust policies → Image Management

Volumes and Storage: Named volumes, bind mounts, volume plugins, storage drivers (overlay, VFS), SQLite backend → Volumes and Storage

REST API and Docker Compatibility: Libpod API, Docker-compatible API endpoints, healthchecks, service socket → REST API

Command Reference: Summary of all major Podman command groups — container, image, pod, network, volume, system, machine, quadlet, kube, artifact → Command Reference