Getting Started with Podman

Podman vs Docker

Podman is a container engine developed primarily by Red Hat. The key differences from Docker are:

Feature	Podman	Docker
Daemon	Daemonless	Requires dockerd daemon
Root privileges	Native rootless container support	Requires extra configuration
Command compatibility	Compatible with Docker CLI	-
Pod support	Native Pod support (similar to Kubernetes)	Not supported
System integration	Uses systemd for container lifecycle management	Own daemon management
Default availability	Included in RHEL/CentOS/AlmaLinux default repositories	Requires third-party repository

Tip

Podman’s command-line interface is fully compatible with Docker. You can seamlessly switch by using alias docker=podman.

Install Podman

RHEL 9 & 10 / AlmaLinux 9 & 10 / Rocky 9 & 10

sudo dnf install -y podman

RHEL 8 / CentOS Stream 8

sudo dnf module install -y container-tools

CentOS 7 (EOL, reference only)

sudo yum install -y podman

Verify the installation:

podman --version
podman info

Pulling and Running Containers

Pull Images

# Pull an image from Docker Hub
podman pull docker.io/library/nginx:latest

# Pull an image from Quay.io
podman pull quay.io/centos/centos:stream9

# List local images
podman images

Note

Podman supports multiple image registries. The default search order can be configured in /etc/containers/registries.conf.

Run Containers

# Run in the foreground, automatically remove on exit
podman run --rm -it centos:stream9 /bin/bash

# Run Nginx in the background, map port 8080 to container port 80
podman run -d --name my-nginx -p 8080:80 docker.io/library/nginx:latest

# Mount a local directory to the container
podman run -d --name my-web \
  -p 8080:80 \
  -v /srv/www:/usr/share/nginx/html:Z \
  docker.io/library/nginx:latest

Caution

When mounting volumes on SELinux-enabled systems, you need to add the :Z or :z suffix to automatically set the correct SELinux context. :Z is a private label (exclusive to one container), while :z is a shared label (shared across multiple containers).

Managing Containers

Check Container Status

# View running containers
podman ps

# View all containers (including stopped ones)
podman ps -a

# View container details
podman inspect my-nginx

# View container logs
podman logs my-nginx

# Follow logs in real time
podman logs -f my-nginx

Stop and Remove Containers

# Stop a container
podman stop my-nginx

# Start a stopped container
podman start my-nginx

# Restart a container
podman restart my-nginx

# Remove a stopped container
podman rm my-nginx

# Force remove a running container
podman rm -f my-nginx

# Remove all stopped containers
podman container prune

Enter a Running Container

# Enter a container with an interactive terminal
podman exec -it my-nginx /bin/bash

# Execute a single command inside a container
podman exec my-nginx cat /etc/nginx/nginx.conf

Building Images

Write a Containerfile

Create a Containerfile (equivalent to a Dockerfile):

FROM docker.io/library/almalinux:9-minimal

# Install application
RUN microdnf install -y httpd && microdnf clean all

# Copy configuration and web files
COPY index.html /var/www/html/index.html
COPY httpd.conf /etc/httpd/conf/httpd.conf

# Expose port
EXPOSE 80

# Start command
CMD ["/usr/sbin/httpd", "-D", "FOREGROUND"]

Build and Run

# Build the image, -t specifies name and tag
podman build -t my-httpd:v1 .

# View the built image
podman images

# Run a container using the custom image
podman run -d --name web -p 8080:80 my-httpd:v1

Export and Import Images

# Save an image to a tar file
podman save -o my-httpd-v1.tar my-httpd:v1

# Load an image from a tar file
podman load -i my-httpd-v1.tar

Using podman-compose

podman-compose is a compatible alternative to Docker Compose.

Install podman-compose

# Prefer the packaged version (EPEL / distribution repos; the package name varies by EL release, so check once)
sudo dnf install -y podman-compose || sudo dnf install -y python3-podman-compose

# Do not `pip3 install podman-compose` system-wide: on EL9/EL10 the system Python may enforce
# PEP 668 (externally-managed-environment) and refuse the install; if you must use pip, use a venv.

Write a Compose File

Create docker-compose.yml:

version: "3"
services:
  web:
    image: docker.io/library/nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:Z
    depends_on:
      - app

  app:
    image: docker.io/library/python:3.11-slim
    working_dir: /app
    volumes:
      - ./app:/app:Z
    command: python3 -m http.server 5000
    ports:
      - "5000:5000"

  db:
    image: docker.io/library/mariadb:10.11
    environment:
      MYSQL_ROOT_PASSWORD: changeme
      MYSQL_DATABASE: myapp
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Start and Manage

# Start all services (in the background)
podman-compose up -d

# View service status
podman-compose ps

# View logs
podman-compose logs -f

# Stop and remove all services
podman-compose down

Tip

The modern approach is to use Quadlet so systemd manages containers natively, rather than relying on podman-compose: podman generate systemd is deprecated, and Quadlet describes containers in declarative .container files with automatic boot startup and restart. Podman 5 (EL 10) also ships a built-in podman compose that can run compose files directly. See Getting Started with Quadlet.

Rootless Containers

Rootless containers are one of Podman’s core advantages, allowing regular users to run containers without root privileges.

Configure a Rootless Environment

1. Verify that UID mapping is configured for the user:

   cat /etc/subuid
   cat /etc/subgid

   If the current user has no entry, add one manually:

   sudo usermod --add-subuids 100000-165535 $(whoami)
   sudo usermod --add-subgids 100000-165535 $(whoami)

2. Run a container as a regular user:

   podman run -d --name rootless-nginx -p 8080:80 docker.io/library/nginx:latest

3. Verify container process ownership:

   ps aux | grep nginx
   podman top rootless-nginx

Caution

Rootless containers cannot bind to privileged ports below 1024. To bind to ports 80/443, you can modify a kernel parameter:

sudo sysctl net.ipv4.ip_unprivileged_port_start=80

Write this configuration to a file in /etc/sysctl.d/ to make it permanent.

Manage Rootless Containers with systemd

Prefer Quadlet (Podman 4.4+ systemd integration, available on EL9/EL10 — see Quadlet). podman generate systemd is deprecated upstream and is kept here only so old deployments can be read; the rest of this page already recommends Quadlet.

# Legacy (deprecated): generate a systemd unit for an existing container
podman generate systemd --name rootless-nginx --files --new

# Move the generated file to the user systemd directory
mkdir -p ~/.config/systemd/user/
mv container-rootless-nginx.service ~/.config/systemd/user/

# Reload and enable the service
systemctl --user daemon-reload
systemctl --user enable --now container-rootless-nginx.service

# Allow user services to continue running after the user logs out
loginctl enable-linger $(whoami)

Check the service status:

systemctl --user status container-rootless-nginx.service

Quadlet: the recommended approach on EL 9+

Tip

Since Podman 4.4 (EL 9.2+), the official recommendation is to use Quadlet instead of podman generate systemd, which is now deprecated. The latter produces “snapshot” unit files that must be regenerated whenever container parameters change; Quadlet lets you describe a container declaratively in a .container file, which systemd converts into a service unit at startup — cleaner and easier to maintain.

Where Quadlet files go:

• System level (root): /etc/containers/systemd/
• User level (rootless): ~/.config/containers/systemd/

Create a .container file describing the container:

~/.config/containers/systemd/nginx.container

[Unit]
Description=Nginx (managed by Quadlet)
After=network-online.target

[Container]
Image=docker.io/library/nginx:latest
PublishPort=8080:80
# Volume mounts get SELinux labels automatically, equivalent to :Z
Volume=%h/nginx/html:/usr/share/nginx/html:Z

[Service]
Restart=always

[Install]
# Start automatically on boot (user login)
WantedBy=default.target

Apply the configuration:

# Have systemd re-read the files and generate nginx.service
systemctl --user daemon-reload
systemctl --user start nginx.service

# Check status (the service name is the filename: .container -> .service)
systemctl --user status nginx.service

# Keep rootless containers running after the user logs out
loginctl enable-linger $(whoami)

To change the container config, just edit the .container file and daemon-reload — no need to regenerate the unit as with podman generate systemd. For system-level units, place the file in /etc/containers/systemd/ and use systemctl (without --user).

Podman Pod Management

Pods are a unique Podman feature, similar to the Kubernetes Pod concept, where multiple containers share the same network namespace.

# Create a Pod with port mappings
podman pod create --name my-pod -p 8080:80 -p 3306:3306

# Run Nginx in the Pod
podman run -d --pod my-pod --name pod-nginx docker.io/library/nginx:latest

# Run MariaDB in the same Pod
podman run -d --pod my-pod --name pod-db \
  -e MYSQL_ROOT_PASSWORD=changeme \
  docker.io/library/mariadb:10.11

# View Pod status
podman pod ps
podman pod inspect my-pod

# Stop and remove a Pod (affects all containers in the Pod)
podman pod stop my-pod
podman pod rm my-pod

Common Maintenance Commands

# Clean up unused images
podman image prune

# Clean up all unused resources (images, containers, volumes)
podman system prune -a

# View disk usage
podman system df

# View container resource usage
podman stats

EL 10 Notes: Podman 5

EL 10 upgrades Podman from 4.x to Podman 5.x. Key changes:

Feature	Podman 4.x (EL 9)	Podman 5.x (EL 10)
Rootless network backend	slirp4netns	pasta (default)
Performance	Baseline	Better network performance
API compatibility	-	Mostly compatible with Podman 4.x

Rootless network backend change

On EL 10, rootless containers use pasta as the network backend by default (replacing slirp4netns), which generally offers better performance with no extra configuration. If needed, you can switch back:

Install slirp4netns (for legacy behavior)

sudo dnf install slirp4netns

Verify Podman version

podman --version
podman info | grep -i network

Tip

For most users, Podman 5.x changes are transparent. If containers on EL 10 have network issues, check whether the pasta backend is the cause — you can switch network modes in containers.conf.