Docker ps is a command-line tool that displays a list of currently running containers in the Docker environment. It shows container IDs, associated images, start times, status, and port mappings. The command is part of the Docker CLI and runs directly on the host system.
When you run docker ps, Docker queries the Docker daemon to retrieve metadata about containers that are actively executing. This includes the container's unique ID, the image it was created from, the command it's running, its current state (running, exited), and any published ports. The output is formatted in a tabular layout for easy reading.
For example, running docker ps in a terminal returns output like:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a1b2c3d4e5f6 nginx:latest "nginx -g 'daemon off" 2 minutes ago Up 2 minutes 80/tcp web-server
This tells you that a container based on the nginx:latest image is running, named web-server, and listening on port 80. The container has been active for two minutes.
Docker ps communicates with the Docker daemon via the Unix socket at /var/run/docker.sock on Linux systems or a named pipe on Windows. The daemon maintains a registry of all containers-both running and stopped-and tracks their lifecycle events.
By default, docker ps only shows containers that are currently running. To see all containers-including those that have stopped or exited-use the -a flag: docker ps -a. This reveals containers that were previously active but are no longer running, which is useful for troubleshooting failed deployments.
The command supports filtering through flags. For example, docker ps --filter "status=exited" lists only containers that have terminated. You can also filter by name (--filter "name=web") or image (--filter "image=redis"). These filters reduce noise when managing large numbers of containers.
Each column in the docker ps output provides actionable insight into container behavior. Here's what each field means:
| Field | Description | Example |
|---|---|---|
| CONTAINER ID | Unique identifier assigned by Docker. Used to reference the container in other commands. | a1b2c3d4e5f6 |
| IMAGE | Name and tag of the base image used to create the container. | nginx:latest |
| COMMAND | Primary process executed inside the container. | "nginx -g 'daemon off'" |
| CREATED | Time since the container was started. | 2 minutes ago |
| STATUS | Current state: Up, Exited, or Restarting. |
Up 2 minutes |
| PORTS | List of host ports mapped to container ports. | 80/tcp |
| NAMES | User-defined or auto-generated name for the container. | web-server |
These fields help identify misbehaving containers, verify service availability, and debug network issues. For instance, if a web app isn't responding on port 80, checking docker ps confirms whether the container is actually running and exposing the correct port.
Developers use docker ps daily during application development and deployment. It's the first step in verifying that services are up after running docker-compose up or docker run.
Suppose you're testing a Node.js app using a Dockerfile. After building and running the container with docker run -d -p 3000:3000 myapp, you run docker ps and see:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f4e5d6c7b8a9 myapp:1.0 "node server.js" 1 minute ago Up 1 minute 0.0.0.0:3000->3000/tcp app-container
The presence of Up 1 minute and 3000->3000/tcp confirms the app is running and accessible locally at http://localhost:3000.
A common mistake is assuming a container is running because it appears in docker ps output. But if the status says Exited (1), the container crashed. Exit code 1 usually indicates a failure in the startup script. Use docker logs <container-id> to inspect error messages.
Docker ps does not show processes inside containers. It only reports on the container's lifecycle and configuration. To check what's happening inside a running container, use docker exec -it <container-id> sh to open a shell session.
Also, docker ps doesn't display resource usage like CPU or memory. For that, use docker stats, which streams real-time metrics. docker ps is purely for visibility into container states and metadata.
Another confusion arises from the difference between docker ps and docker ps -a. New users often expect docker ps to show all containers. It does not. Only -a includes stopped ones. This distinction matters when cleaning up old containers or diagnosing failed builds.
One non-obvious detail: the NAMES column uses random names like happy_williams if you don't assign a custom name. These names are generated from a list of adjectives and famous scientists. You can override them with --name <custom-name> during creation.
I once spent 20 minutes debugging a missing API endpoint until I ran docker ps and saw the container had exited with code 137. That's an out-of-memory error. The container was being killed by the OS due to insufficient RAM. I increased the memory limit in the compose file and restarted. The fix took less than five minutes after identifying the issue with docker ps.
Combine docker ps with other commands for deeper insights:
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" - Custom output format for scripting.docker logs <container-id> - View application logs from a running container.docker stop <container-id> - Gracefully shut down a running container.docker rm <container-id> - Remove a container after stopping it.Use docker ps --help to see all available options. The command supports JSON output via --format json, which is useful for integration with monitoring tools.
Running docker ps gives immediate visibility into your containerized environment. It's a core diagnostic tool for anyone working with Docker. Knowing what it shows-and what it doesn't-prevents wasted time and ensures faster troubleshooting.