podman

name: podman description: Use when the user asks about Podman, rootless containers, Quadlet/systemd units, Podman Compose, or migrating Docker workflows to Podman. Creates and manages rootless Podman containers, maps Docker commands, configures podman run/build/compose flows, and sets up systemd-managed services. metadata: references: - references/rootless-containers.md - references/docker-compatibility.md - references/operations-and-troubleshooting.md assets: - assets/podman-compose-example.yml - assets/quadlet-example.container

Primary Actions

Run and manage rootless Podman containers.
Translate Docker workflows to Podman equivalents.
Configure Podman Compose for multi-service stacks.
Create systemd-managed services using Quadlet.
Troubleshoot rootless, socket, and service lifecycle issues.

Quick Command Map (Differences from Docker)

# Docker socket compatibility
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

# Pod operations (Podman-specific)
podman pod create --name app-pod

# Quadlet service management
systemctl --user daemon-reload
systemctl --user enable --now my-service

Rootless Container Example

# Run a container without root — this is the Podman default
podman run --rm -it alpine sh

# Verify rootless mode
podman info --format '{{ .Host.Security.Rootless }}'   # should print: true

# Verify user namespace mapping (uid 0 in container = your UID on host)
podman unshare cat /proc/self/uid_map

Quadlet Unit Example

Place .container files in ~/.config/containers/systemd/ (user) or /etc/containers/systemd/ (system):

# ~/.config/containers/systemd/myapp.container
[Unit]
Description=My App Container

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=8080:80
Volume=%h/data:/usr/share/nginx/html:Z

[Service]
Restart=always

[Install]
WantedBy=default.target

# Load and start
systemctl --user daemon-reload
systemctl --user enable --now myapp

# Validate
systemctl --user status myapp
journalctl --user -u myapp -n 50

See assets/quadlet-example.container for a more complete example.

Translate Docker → Podman

Docker	Podman	Notes
`docker run`	`podman run`	Identical flags; rootless by default
`docker build`	`podman build`	Identical Dockerfile syntax
`docker ps`	`podman ps`	Same output
`docker compose up`	`podman-compose up`	Or use Docker Compose CLI via socket
`docker system prune`	`podman system prune`	Same
Daemon required	No daemon	Podman is daemonless

Validation Workflow

Verify rootless mode:

podman info --format '{{ .Host.Security.Rootless }}'   # → true
podman unshare cat /proc/self/uid_map                   # → uid mapping present

Run a basic rootless container:
```
podman run --rm hello-world
```

For Compose, validate config before up:

podman-compose config
podman-compose up --dry-run   # if supported by your version

For Quadlet, verify systemd unit status and logs:

systemctl --user status myapp
journalctl --user -u myapp --since "5 minutes ago"

If failures occur, fix and re-run the relevant check.

Deep References

Rootless architecture, networking, volume permissions: references/rootless-containers.md
Docker compatibility details and known differences: references/docker-compatibility.md
Validation and troubleshooting playbook: references/operations-and-troubleshooting.md