podman run: Run Containers in Pipelines
podman run creates a container from an image and starts it, mirroring docker run flag for flag.
podman run is the workhorse for spinning up service containers in tests. The flags match docker run; the differences show up around rootless networking and privileged ports.
What it does
podman run pulls the image if needed, creates a container, and starts it with the command you give. It supports the same -d, --rm, -e, -v, and -p flags as docker run, running rootless by default with no daemon involved.
Common usage
podman run --rm hello-world
podman run -d --name db -e POSTGRES_PASSWORD=test -p 5432:5432 docker.io/library/postgres:16
podman run --rm -v "$PWD":/work:Z -w /work docker.io/library/node:20 npm testOptions
| Flag | What it does |
|---|---|
| -d, --detach | Run the container in the background |
| --rm | Remove the container when it exits |
| --name <name> | Assign a name to the container |
| -e, --env <k=v> | Set an environment variable |
| -v, --volume <src:dst> | Bind mount a host path (add :Z for SELinux relabel) |
| -p, --publish <h:c> | Publish a container port to the host |
In CI
Rootless Podman cannot bind host ports below 1024 by default, so map to a high port (-p 8080:80) or lower net.ipv4.ip_unprivileged_port_start. With SELinux runners, add :Z to bind mounts so the container can read the volume.
Common errors in CI
"rootlessport cannot expose privileged port 80" means you tried to publish a port below 1024 as a rootless user; use a high host port. "cannot set up namespace ... newuidmap: write to uid_map failed" means missing subuid/subgid ranges. "Permission denied" reading a bind mount on an SELinux host is fixed by adding :Z to the -v option. "short-name ... no resolution" means an unqualified image name; use the fully qualified docker.io/... form.