Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Containers and Images

Managing Containers: ps, logs, exec, inspect, cp

Day-to-day Podman container management: list and filter with ps, read logs, exec, copy files, inspect with Go templates, check stats, rename, commit and clean up.

Once a few containers are running, the skill that matters is finding out what they are doing. Podman gives you a set of small commands for that: list, filter, log, inspect, run commands, copy files, watch resource use, and clean up. This lesson collects them with the patterns that save time in practice.

Most commands accept a container name, a full ID or a unique ID prefix. Many accept --latest (-l) to mean "the most recently created container", which is convenient when you are typing quickly on your own machine, but never use it in scripts, where it can pick the wrong one.

Listing and filtering

Terminal
podman ps                        # running
podman ps -a                     # all, including stopped
podman ps -a --filter status=exited
podman ps --filter name=web --filter label=app=shop
podman ps --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
podman ps --format json
podman ps --quiet                # IDs only, handy in scripts

--filter can be repeated; different keys combine with AND. Common keys are name, status, label, ancestor (image), network and volume. The --format option takes a Go template, and table adds a header row:

Terminal
podman ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}'

Logs

Terminal
podman logs web
podman logs --tail 20 web
podman logs --since 10m --timestamps web
podman logs --follow web

Podman stores logs through a log driver. In rootless mode the default is often k8s-file (a file in the container's directory) or journald when the system supports it. With journald, you can also use journalctl --user CONTAINER_NAME=web. Remember that logs only contain what the program writes to standard output and standard error: a program that logs to a file inside the container needs a different approach, such as symlinking that file to /dev/stdout.

Running commands and copying files

Terminal
podman exec web ls /usr/share/nginx/html
podman exec -it web sh
podman exec --user root -w /tmp web id
podman exec --env DEBUG=1 web env

exec works only on a running container. If a container exits right away and you need to look around inside, start a shell in its image instead (podman run --rm -it --entrypoint sh IMAGE), or use podman commit and debug the snapshot.

Copy files in either direction with podman cp; the container side is written as NAME:/path:

Terminal
podman cp ./index.html web:/usr/share/nginx/html/index.html
podman cp web:/etc/nginx/nginx.conf ./nginx.conf

cp is for quick fixes and for pulling out a file. Anything you copy in is lost when the container is removed, so real changes belong in an image build or in a volume.

Inspecting

Terminal
podman inspect web
podman inspect --format '{{.State.Status}}' web
podman inspect --format '{{.NetworkSettings.IPAddress}}' web
podman inspect --format '{{json .Config.Env}}' web
podman inspect --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}' web

The full JSON is long. Learn the handful of paths you use: .State (status, pid, exit code, health), .Config (image, command, environment, labels), .HostConfig (ports, limits, restart policy), .Mounts and .NetworkSettings. The command also accepts --type image|volume|network|pod to inspect other objects.

Here is a stand-in that shows how to pick fields out of nested data and how filters combine. It uses made-up data in JavaScript, not output from Podman.

JS Stand-in: filter and format a container list

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

No output.

Resource usage and processes

Terminal
podman stats                 # live table; Ctrl+C to leave
podman stats --no-stream     # one snapshot
podman top web               # processes inside the container
podman top web user pid args
podman port web              # published ports
podman diff web              # files added (A), changed (C), deleted (D) in the writable layer

podman diff is great for answering "what has this container changed compared with its image?", and it shows why you should not rely on the writable layer for data. In rootless mode, podman stats needs cgroups v2.

Changing and renaming

Terminal
podman rename web frontend
podman update --memory 512m frontend      # change some limits on a running container
podman pause frontend ; podman unpause frontend
podman restart frontend
podman kill --signal HUP frontend         # send a signal, e.g. reload config
podman wait frontend                      # block until it exits, print the exit code

podman wait is useful in shell scripts: start a job container, wait, and check the exit code. podman restart stops and starts again, keeping the same container and writable layer. podman update can change resource limits and the restart policy without recreating the container, but not ports or mounts: those need a new container.

Commit and export (and why not to)

Terminal
podman commit web my-nginx:snapshot       # turn a container into an image
podman export web > web-fs.tar            # the file system as a tar, without layers

commit is good for investigation, but it is a poor way to build images, because nobody can see what was changed and the result cannot be rebuilt. Write a Containerfile instead (Building and Registries later in this course covers it).

Removing

Terminal
podman stop web && podman rm web
podman rm --force web                 # stop (kill) and remove
podman rm --all --force               # remove every container, running or not
podman container prune                # remove stopped containers only
podman rm --volumes web               # also remove anonymous volumes created for it

podman rm -a -f is a sharp tool. Use podman ps -a first, and remember that removing a container removes its writable layer and anonymous volumes. Named volumes remain.

A routine for debugging a container that will not start

  1. podman ps -a โ€” is it Exited? Note the exit code in the status text.
  2. podman logs NAME โ€” the program usually says what went wrong.
  3. podman inspect --format '{{.State.ExitCode}} {{.State.Error}}' NAME โ€” separates program errors from start errors.
  4. podman run --rm -it --entrypoint sh IMAGE โ€” look around in a clean copy.
  5. Compare the options with podman inspect NAME to find a bad mount path, port or user.

Common exit codes: 0 success, 1 general error, 125 Podman itself failed, 126 command could not run (permissions), 127 command not found, 137 killed (often out of memory or podman kill), 143 stopped by SIGTERM.

JS Stand-in: decode an exit code

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

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command lists stopped containers too?

    podman ps shows only running containers. --all (-a) includes the ones that exited or were created but not started.
  2. 2. How do you read just the container's status with a Go template?

    inspect returns JSON; --format uses a template to select a path like .State.Status.
  3. 3. What does podman diff web show?

    It compares the container's file system with its image and labels entries A, C and D.
  4. 4. A container's exit code is 137. What is the most likely meaning?

    Exit codes above 128 mean 128 plus a signal number; 137 is SIGKILL (9).
  5. 5. Why is podman commit a weak way to produce images?

    A Containerfile records every step and can be rebuilt. A committed snapshot hides what changed.

Summary

  • podman ps with --filter and --format finds containers; --quiet gives IDs for scripts.
  • logs, exec, cp, top, stats, diff and port show what is happening inside.
  • inspect --format with Go templates extracts exactly the field you need.
  • rename, update, restart, kill and wait change or control running containers.
  • commit and export exist but are not a substitute for a Containerfile.
  • Debug a failing container with status, logs, exit code, then a clean shell in its image.

Next: Pulling and Searching Images