Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Containers and Images

podman run Options in Depth

Master podman run: environment variables, ports, names, working directory, user, entrypoint, resource limits, restart policy, init and read-only file systems.

podman run is the command you will type most often, and almost everything interesting about a container is set by one of its options. Learning the options by group makes them easy to remember: how the container is named and run, what environment it sees, how it is reached, what resources it may use, and how restricted it is.

This lesson walks through those groups with the options you will use in real projects. Every option appears before the image name; the image is followed by an optional command that replaces the image's default.

Name, mode and cleanup

Option Meaning
--name NAME give the container a name (must be unique)
-d, --detach run in the background
-it interactive with a terminal (-i keeps stdin open, -t allocates a TTY)
--rm remove the container when it exits
--pull=missing|always|never|newer when to pull the image (default: only if missing)
--label KEY=VALUE attach metadata you can filter on later
--replace if a container with this name exists, remove it first

--replace is handy in scripts and systemd units, because it makes "start this container" safe to repeat. Labels are free-form tags: podman ps --filter label=team=web lists only matching containers.

Environment variables and working directory

Terminal
podman run --rm \
  --env GREETING=hello \
  --env-file ./app.env \
  --workdir /srv \
  docker.io/library/alpine:latest sh -c 'echo "$GREETING from $(pwd)"'
  • -e NAME=value (or --env) sets a variable. -e NAME without a value copies it from your shell.
  • --env-file FILE reads NAME=value lines; comments start with #. The file is easy to keep out of Git, unlike a long command.
  • -w / --workdir sets the starting directory inside the container.
  • --hostname NAME sets the container's hostname.

Environment variables are visible in podman inspect and to anything that can read the process's environment. For passwords and keys, prefer Podman secrets (Secrets and Image Trust) instead of -e.

Ports

Terminal
podman run -d -p 8080:80 docker.io/library/nginx:alpine           # host 8080 -> container 80
podman run -d -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine # only reachable from this machine
podman run -d -p 8080:80/udp some-image                           # a UDP port
podman run -d -P docker.io/library/nginx:alpine                   # publish all EXPOSEd ports to random host ports

Binding to 127.0.0.1 is a good default for databases and admin tools, so they are not exposed to your network by accident. podman port NAME prints the mapping.

User and identity

--user chooses which user inside the container runs the process:

Terminal
podman run --rm --user 1000:1000 docker.io/library/alpine:latest id

Many official images already switch to an unprivileged user. Running as non-root inside the container is good practice even under rootless Podman, as a second layer. See Rootless and User Namespaces for how those numbers map to the host.

Entrypoint and command

An image defines an ENTRYPOINT (the program) and a CMD (its default arguments). Whatever you write after the image replaces CMD; --entrypoint replaces the program.

Terminal
# image default
podman run --rm docker.io/library/alpine:latest              # runs its default (a shell, exits at once)
# replace CMD
podman run --rm docker.io/library/alpine:latest echo hi
# replace ENTRYPOINT
podman run --rm --entrypoint /bin/cat docker.io/library/alpine:latest /etc/os-release

The rule for the interplay: the final command line is ENTRYPOINT + CMD, where words after the image replace CMD. Here is a stand-in that models this rule so you can try combinations. It is JavaScript, not Podman.

JS Stand-in: ENTRYPOINT and CMD combined

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Resource limits

Limits are enforced by Linux cgroups:

Terminal
podman run -d --name capped \
  --memory 256m \
  --memory-swap 256m \
  --cpus 1.5 \
  --pids-limit 200 \
  docker.io/library/nginx:alpine
  • --memory is the hard memory limit; the kernel kills the process (OOM) if it goes beyond.
  • --memory-swap is memory plus swap; equal to --memory means no swap.
  • --cpus 1.5 allows one and a half CPUs of time. --cpu-shares sets a relative weight.
  • --pids-limit caps the number of processes, which stops fork bombs.

In rootless mode, controlling cgroups needs cgroups v2 and systemd to delegate the controllers to your user. Most current distributions do this for memory and pids; CPU may need a delegation setting. If a limit is ignored, Podman prints a warning. podman stats shows live usage against the limits.

Here is a tiny stand-in that decides whether a process would be killed under a memory limit. It is illustration only.

JS Stand-in: memory limit check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Restart policy and init

Terminal
podman run -d --restart on-failure:3 --name worker some-image
podman run -d --init --name web docker.io/library/nginx:alpine

--restart accepts no (default), on-failure[:max], always and unless-stopped. It restarts when the container exits, but not after a reboot unless a systemd service restores them; Health Checks and Restart Policies goes deeper. --init runs a tiny init program (catatonit) as process 1. It reaps zombie child processes and forwards signals, which matters for programs that spawn many children.

Read-only and temporary file systems

Terminal
podman run -d --read-only --tmpfs /tmp --tmpfs /run docker.io/library/nginx:alpine

--read-only makes the container's root file system read-only, so an attacker (or a bug) cannot modify programs. Programs that need scratch space get it through --tmpfs, memory-backed directories. nginx also wants to write its cache and PID file, so a real setup adds writable volumes for those paths; the point is that you decide which paths are writable.

Putting it together

Terminal
podman run -d --name api \
  --replace \
  --restart on-failure:5 \
  --env-file ./api.env \
  --memory 512m --cpus 1 --pids-limit 256 \
  --read-only --tmpfs /tmp \
  --user 10001:10001 \
  -p 127.0.0.1:8081:8080 \
  --label app=api \
  registry.example.com/team/api:1.4.2

Every line is a decision that can be reviewed in a pull request. Later in the course you will move this into a Quadlet file, where each option has an equivalent key.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which option removes the container automatically after it exits?

    --rm deletes the container when its main process ends. --replace removes an older container with the same name before starting.
  2. 2. What does -p 127.0.0.1:8080:80 do compared with -p 8080:80?

    Specifying 127.0.0.1 binds the host side to the loopback address, so other computers cannot connect.
  3. 3. You run podman run --rm --entrypoint /bin/cat IMAGE /etc/os-release. What replaces what?

    --entrypoint swaps the program, and the words after the image are the new arguments.
  4. 4. What does --memory-swap equal to --memory mean?

    memory-swap is memory plus swap. When it equals memory, there is no swap space left for the container.
  5. 5. Why is --init useful?

    A real init process as PID 1 handles orphaned children and signals correctly.

Summary

  • Options for naming and mode: --name, -d, -it, --rm, --replace, --label.
  • Environment: -e, --env-file, --workdir, --hostname; avoid putting secrets in environment variables.
  • Ports use -p [ip:]host:container[/proto]; bind to 127.0.0.1 when the service is private.
  • --user, --entrypoint and the command after the image control who runs what.
  • Limits (--memory, --cpus, --pids-limit) use cgroups; rootless needs cgroups v2 delegation.
  • --restart, --init, --read-only and --tmpfs make containers more robust and safer.

Next: Managing Containers