Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First Podman Container

Run your first Podman container, publish a port, read its logs, open a shell inside it, then stop and remove it. A step-by-step guide to the core commands.

Time to run something. In this lesson you will start a web server in a container, look at it from the outside, step inside, and clean it up. These five or six commands are the ones you will use every day, so it is worth doing each by hand.

All commands here run as a normal user. If you are on macOS or Windows, make sure podman machine start has been run first. The examples use fully qualified image names such as docker.io/library/nginx:alpine, which is the safest habit: it says exactly which registry you mean (Pulling and Searching Images explains why).

Run a container

Terminal
podman run --detach --name hello-web --publish 8080:80 docker.io/library/nginx:alpine

Break it down:

  • podman run creates a container from an image and starts it.
  • --detach (or -d) puts it in the background and prints the new container's ID.
  • --name hello-web gives it a name you can use instead of the ID.
  • --publish 8080:80 (or -p) forwards port 8080 on your computer to port 80 in the container.
  • docker.io/library/nginx:alpine is the image: registry, namespace, name and tag.

The first time, Podman downloads the image layers and prints progress. The next run starts almost instantly, because the image is now in local storage.

Open http://localhost:8080 in a browser, or use curl:

Terminal
curl -s http://localhost:8080 | head -n 5

You should see the HTML of the default nginx welcome page. That is a real web server, running in a container, reachable from your host.

See what is running

Terminal
podman ps
podman ps --all

podman ps lists running containers: ID, image, command, how long ago it was created, status, ports and name. Add --all (-a) to include stopped ones. The ID is a long hexadecimal string, and the table shows its first 12 characters. You may use any unique prefix of an ID, or the name, in other commands.

Read the logs

Terminal
podman logs hello-web
podman logs --follow hello-web

Anything the program writes to standard output or standard error is captured. After the curl above you should see an access-log line for your request. --follow (-f) keeps the log open like tail -f; stop it with Ctrl+C, which does not stop the container.

Open a shell inside

Terminal
podman exec -it hello-web sh

exec starts a new process inside a running container. -i keeps your input connected and -t gives you a terminal, so together they make an interactive shell. The alpine-based image ships sh, not bash. Inside, try ls /usr/share/nginx/html and cat /etc/os-release, then type exit. You leave the shell; the web server keeps running, because you only ended the extra process.

Run a one-off command

Not every container is a server. Often you just want to run a command in a clean environment and throw the container away:

Terminal
podman run --rm docker.io/library/alpine:latest echo "hello from a container"

--rm deletes the container when it exits. Without it, a stopped container stays around (visible in podman ps -a) until you remove it. For quick experiments, use --rm almost always.

For a throwaway interactive session in any image:

Terminal
podman run --rm -it docker.io/library/alpine:latest sh

Stop and remove

Terminal
podman stop hello-web
podman ps --all
podman rm hello-web

podman stop sends the container's main process a termination signal (SIGTERM) and waits up to 10 seconds before it forces it with SIGKILL. The container still exists, in the "exited" state: you can start it again with podman start hello-web. podman rm deletes it. A running container needs podman rm --force (or stop it first).

The life of a container is a small state machine:

stateDiagram-v2
    [*] --> Created: podman create
    Created --> Running: podman start
    [*] --> Running: podman run
    Running --> Exited: process ends or podman stop
    Exited --> Running: podman start
    Running --> Paused: podman pause
    Paused --> Running: podman unpause
    Exited --> [*]: podman rm

The states a container passes through. podman run is create plus start in one step.

IDs and names

Every container has a 64-character ID, and the short form is its first 12 characters. If you do not give --name, Podman invents a friendly name from two words, which is why you see names like quirky_hertz in listings. Here is a stand-in that mimics how a short ID relates to the full one. It uses a simple hash and is not how Podman makes IDs.

JS Stand-in: full ID versus short ID

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

No output.

A mistake to avoid

The most common first-day error is putting an option after the image name:

Terminal
# Wrong: --rm goes to the program inside the container
podman run docker.io/library/alpine:latest --rm echo hi

# Right: Podman's options first, then the image, then the command
podman run --rm docker.io/library/alpine:latest echo hi

Another one: choosing a host port that is already in use. If 8080 is busy, you get an error such as "address already in use". Pick a different host port, for example -p 8081:80. Rootless Podman also refuses to publish ports below 1024 by default, which Rootless Ports, Networking and Storage explains.

Here is a stand-in that mirrors the lifecycle commands as a tiny state machine. It lets you try the transitions, including illegal ones, without a real container.

JS Stand-in: container state machine

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

No output.

Cleaning up everything

When you experiment a lot, stopped containers pile up. These commands tidy up:

Terminal
podman container prune     # remove all stopped containers
podman image prune         # remove dangling images
podman system prune        # remove stopped containers, unused networks, dangling images

Each asks for confirmation unless you add --force. Be careful with podman system prune --all: it also removes images that no container currently uses, so you must download them again later.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the --rm option do?

    --rm deletes the container as soon as its main process ends, so no stopped container is left behind.
  2. 2. How do you start an interactive shell in a container that is already running?

    exec starts an additional process in an existing container. -i and -t connect your keyboard and give a terminal.
  3. 3. After podman stop web, what is the state of the container?

    Stopping ends the main process but keeps the container. podman start brings it back; podman rm deletes it.
  4. 4. Where must Podman's own options go in podman run?

    Everything after the image name is passed to the program in the container, so Podman's flags must come before it.

Summary

  • podman run creates and starts a container; -d backgrounds it, --name names it, -p host:container publishes a port.
  • podman ps (and -a), podman logs, and podman exec -it let you inspect and enter containers.
  • podman stop, podman start and podman rm move a container through its lifecycle.
  • Use --rm for throwaway containers so they clean up after themselves.
  • Options for Podman go before the image name, the command goes after it.
  • podman container prune and podman system prune remove leftovers.

Next: Podman vs Docker