Listing and Inspecting Containers: A Docker CLI Guide

Previously in this course, we covered Managing Container States, where you learned how to start and stop containers. While starting and stopping is essential, it’s useless if you can’t see what’s happening under the hood. Today, we’re leveling up your visibility by using the Docker CLI to track, identify, and inspect every container on your system.

Understanding the Container Landscape with docker ps

When you first start with Docker, you likely reach for docker ps to see what's running. However, docker ps only shows you active containers. In a real-world scenario, you’ll frequently need to troubleshoot containers that have crashed or finished their tasks—these don't disappear, they just stop.

To view everything, we use the --all (or -a) flag:

Bash
docker ps -a

When you run this, you’ll see several columns. The most critical is the CONTAINER ID. This is the unique identifier Docker uses to track your instance. While the output shows a short hash (e.g., a1b2c3d4e5f6), Docker recognizes the full, long-form ID. You can usually get away with typing just the first 3-4 characters of the ID when running commands, as long as they are unique.

Deep Diving with docker inspect

Sometimes you need more than just the status of a container. You might need to know its IP address, the environment variables it's using, or the exact path where its volumes are mounted. This is where docker inspect becomes your most powerful tool.

The docker inspect command returns a massive JSON object containing the container's entire configuration and state.

Worked Example: Inspecting a Container

1. Ensure you have a container running (use docker run -d nginx if you need one).
2. Get the ID: docker ps.
3. Inspect it:

   Bash
   docker inspect <container-id>
   

The output can be overwhelming. To find specific information, like the container’s IP address, you can use the --format flag to query the JSON directly:

Bash
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container-id>

Accessing Container Logs

If your application isn't behaving as expected, the first place you should look is the logs. Even if a container has stopped, its logs persist until you remove the container.

To see the output generated by a container, use:

Bash
docker logs <container-id>

If you are debugging a live issue, you often want to follow the logs in real-time, just like tail -f in Linux:

Bash
docker logs -f <container-id>

Hands-on Exercise: The Identification Hunt

Let’s put this into practice. Follow these steps to map your environment:

1. Start three separate containers using docker run -d alpine sleep 100.
2. Stop one of those containers using docker stop <container-id>.
3. Use docker ps -a to list all three containers and identify which one is in the Exited state.
4. Run docker inspect on the stopped container and search for the "State" field in the JSON output to confirm its "Status" is "exited".
5. Run docker logs on one of the running containers to see the system output.

Common Pitfalls

• Forgetting the -a flag: Beginners often think they’ve lost their containers because they don't see them in docker ps. Remember, if it’s not running, it’s hidden from the default view.
• Confusing Image IDs with Container IDs: docker ps shows container IDs. docker images (which we will cover later) shows image IDs. They are not interchangeable.
• Overwhelming output: docker inspect returns a wall of text. Don't try to read it all. Use tools like grep or the --format flag to extract the specific metadata you need.

FAQ

Q: Can I rename my containers to make them easier to identify? A: Yes! When running a container, use the --name flag: docker run --name my-web-server -d nginx. This makes it much easier to reference the container by name instead of a cryptic ID.

Q: How do I see only the IDs of my containers? A: Use docker ps -aq. The -q (quiet) flag is incredibly useful for scripting and passing IDs to other commands, like docker stop $(docker ps -aq).

Recap

In this lesson, we moved beyond basic lifecycle management into observability. You now know that docker ps -a reveals the full state of your environment, docker inspect provides the deep metadata required for debugging, and docker logs is your primary window into a container's health.

Up next: We will learn how to clean up your environment by Removing Containers.