podman inspect gives you the raw, unadulterated JSON representation of a Podman container’s configuration.
Let’s see what a running container looks like under the hood.
# First, start a simple container
podman run -d --name my-nginx -p 8080:80 -v /tmp/nginx-html:/usr/share/nginx/html:ro nginx
# Now, inspect it
podman inspect my-nginx
This will output a massive JSON blob. Don’t be intimidated; it’s all useful.
The most surprising thing about podman inspect is that it doesn’t just show you what you configured; it shows you the entire state of the container, including defaults and runtime-generated values. Think of it as the container’s DNA.
Let’s break down some key sections you’ll find in that JSON output.
The Config section is where your original podman run arguments are reflected. You’ll see Cmd, Entrypoint, Env, ExposedPorts, and Volumes here. For our my-nginx example, you’ll find "ExposedPorts": {"80/tcp": {}}, and under Mounts, you’ll see details about the volume we attached.
The HostConfig section details how the container is configured to run on the host. This includes things like PortBindings (mapping host ports to container ports), Binds (the actual host path to container path mapping for volumes), RestartPolicy, and NetworkMode. In our example, you’ll see "PortBindings": {"80/tcp": [{"HostIp": "", "HostPort": "8080"}]} which clearly shows the 8080 host port mapping to the container’s 80/tcp port.
The State section is the dynamic part, reflecting the container’s current runtime status. It contains Status (e.g., "running", "exited"), Running (boolean), Pid (the process ID on the host), StartedAt, and FinishedAt. This is what tells you if your container is actually alive and kicking.
The GraphDriver section is fascinating. It shows you how the container’s filesystem layers are managed by the storage driver (e.g., overlay, vfs). You’ll see Data containing information like the LowerDir, UpperDir, WorkDir, and MergedDir if you’re using overlayfs. This is crucial for understanding how Podman isolates container filesystems.
The NetworkSettings section provides details about the container’s network interfaces, IP addresses, MAC addresses, and gateway, especially if you’re using Podman’s default CNI networking or a custom network. You’ll see IPAddress, Gateway, and Ports mapped from the container’s perspective.
The sheer volume of information can be overwhelming, but it’s exactly what you need for deep debugging. For instance, if a port isn’t accessible, you’d check HostConfig.PortBindings to ensure the mapping is correct and NetworkSettings.Ports to see what the container itself thinks its listening on.
One aspect many users overlook is the RootFS section, specifically the Layers array. This shows the ordered list of image layers that make up the container’s filesystem. Understanding this order is key to grasping how image immutability and layering work, and it helps diagnose issues related to file conflicts or unexpected behavior stemming from layer interactions.
If you need to programmatically access a specific piece of information, use the --format flag with Go templating. For example, to get just the container’s ID: podman inspect --format '{{.Id}}' my-nginx.
The next logical step after inspecting is often understanding how to modify these configurations, which leads to exploring Podman’s update and commit commands.