Podman on Fedora: install, daily commands, registry mirrors and Quadlet autostart

Fedora ships Podman as its container engine; Docker is not needed. Measured on a Cloud image:

podman --version
podman info --format '{{.Host.Security.Rootless}}'

podman version 6.1.0
true

true means rootless containers work — ordinary users can run containers without sudo.

Note

Division of labour across three pages: this page is how to use it; containers and rootless covers the mechanics (uid mapping, boundaries); Podman 6 covers what changed from 5.x.

If it is not installed

sudo dnf install podman

For scripts that hardcode docker:

sudo dnf install podman-docker

After that docker is a shim over podman and docker ps works.

Daily commands

Run a container:

podman run --rm docker.io/library/alpine echo "hello from podman"

hello from podman

--rm removes it on exit.

Inspect:

podman images --format "{{.Repository}}:{{.Tag}} {{.Size}}"
podman ps -a

docker.io/library/alpine:latest 8.72 MB

docker to podman map

Task	docker	podman
run	docker run	podman run
running list	docker ps	podman ps
all list	docker ps -a	podman ps -a
exec	docker exec -it	podman exec -it
logs	docker logs	podman logs
build	docker build	podman build (or buildah)
compose	docker compose	podman compose / Quadlet
daemon	dockerd	none

That last row matters: Podman calls runc/crun directly and runs no daemon, so there is no systemctl status docker.

Domestic registry mirror

Docker Hub pulls frequently time out here. Add a registry rewrite:

sudo tee /etc/containers/registries.conf.d/99-cn.conf >/dev/null <<'EOF'
unqualified-search-registries = ["docker.io"]

[[registry]]
prefix = "docker.io"
location = "docker.m.daocloud.io"
EOF

Then podman pull nginx goes through the mirror. Measured:

time podman pull -q docker.io/library/alpine

real  0m9.692s

Caution

The [[registry]] block is a full rewrite: once location is set, everything under that prefix comes from the mirror and never falls back to Docker Hub. If the mirror lacks an image, the pull fails rather than falling back.

Volumes and ports

podman run -d --name web \
  -p 8080:80 \
  -v /srv/html:/usr/share/nginx/html:Z \
  docker.io/library/nginx

The trailing :Z is the SELinux label and is mandatory on Fedora — without it the container cannot read the host directory and reports Permission denied (see SELinux).

Verify:

curl -s http://127.0.0.1:8080/ | head -3
podman logs web --tail 3
podman exec -it web sh

Note

After -p 8080:80, remember to allow 8080 in firewalld, or the port is reachable only locally.

Quadlet: containers that start at boot

This is the most useful part. The old podman generate systemd is gone in 6.x — Quadlet replaces it: write a declarative file and systemd generates the unit.

Check the directory and generator:

ls -d /etc/containers/systemd
ls /usr/lib/systemd/system-generators/ | grep podman

/etc/containers/systemd
podman-system-generator

Write a container:

sudo tee /etc/containers/systemd/web.container >/dev/null <<'EOF'
[Unit]
Description=Demo web container

[Container]
Image=docker.io/library/alpine:latest
Exec=sleep infinity

[Install]
WantedBy=default.target
EOF

Reload and look at the generated unit:

sudo systemctl daemon-reload
systemctl status web.service --no-pager | head -5

○ web.service - Demo web container
     Loaded: loaded (/etc/containers/systemd/web.container; generated)
     Active: inactive (dead)

Note generated: this .service is produced from the .container file. Do not edit it by hand.

Start it:

sudo systemctl start web.service
systemctl is-active web.service
podman ps --format "{{.Names}} {{.Status}}"

active
systemd-web Up 2 seconds

The container is named systemd-web (with the systemd- prefix).

User-level Quadlet (rootless, recommended)

mkdir -p ~/.config/containers/systemd
cp /etc/containers/systemd/web.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start web.service

For user services that must run without an active login:

sudo loginctl enable-linger $USER

Tip

loginctl enable-linger is the step people forget. Without it, logging out stops the container.

Migrating from Docker

Docker habit	On Podman
docker compose up	dnf install podman-compose, then podman-compose up, or convert to Quadlet
systemctl restart docker	no daemon; restart the container or its unit
/var/run/docker.sock	podman-docker provides a compatible socket; some tools still need config changes
docker build	podman build — same Dockerfile syntax

sudo systemctl restart docker    # Unit docker.service not found

That error is expected — there is no daemon to restart.

Common traps

Symptom	Cause
podman pull times out	no registry mirror configured, or the mirror lacks the image
mounted directory Permission denied	missing :Z; SELinux blocked it
container has no outbound network	rootless needs --network=host or a working pasta/slirp4netns
Quadlet change has no effect	forgot systemctl daemon-reload after editing the .container
user service stops on logout	missing loginctl enable-linger
systemctl restart docker fails	Podman has no daemon — expected

Related pages

• Containers and rootless — uid mapping and security boundaries
• Podman 6 — what changed in 6.x
• Domestic mirrors — registry mirrors and other ecosystems
• SELinux — why mounts need :Z
• Official: Podman documentation