# podman run: Run Containers in Pipelines

> podman run creates and starts a container from an image. Reference for -d, --rm, -e, -v, -p, and the rootless port and namespace errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-run  
Updated: 2026-06-30

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

```Terminal
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 test
```

## Options

| 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.

## FAQ

### podman run: Run Containers in Pipelines?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt