Guide · Open source
How to use ctop: install, run and read container metrics
Updated · written with AI from the project's own documentation and checked against our catalogue data
ctop is a command-line program that shows real-time resource metrics for many containers at once, in a layout similar to the Linux top command. This guide is for developers and operators who run Docker or runC containers and want a quick terminal overview. After reading it, you will be able to install ctop, start it, filter and sort containers, open a single-container view, and check logs or open a shell from the same screen.
ctopbcicen/ctop · ★ 17.8k · MIT Install options & downloads Quick start
- 1Install ctop. Install ctop with Homebrew, scoop, a Linux package, or download the binary from the releases page.
- 2Confirm Docker or runC is running. ctop needs Docker or runC on the host so it has containers to show.
- 3Start ctop. Run ctop with no arguments. It uses Docker host variables by default.
- 4Show all containers if needed. Press a to toggle display of non-running containers as well as running ones.
- 5Filter and sort. Press f to filter the list and s to choose a sort field. Press r to reverse the order.
- 6Open a single container. Select a container and press o for the single view, l for logs, or e for a shell.
- 7Save your layout. Press S to save the current options to the config file so they load next time.
Install ctop on macOS, Windows or Linux
Fetch the latest release from the ctop GitHub releases page for your platform, or use a package manager where the project lists one. ctop is distributed as a download, so the install is a single program placed on your path.
- macOS with Homebrew: run brew install ctop
- Windows with scoop: run scoop install ctop
- Debian/Ubuntu: a third-party maintained package named docker-ctop is listed in the README
- Arch Linux: install with sudo pacman -S ctop, or from the AUR as ctop-bin
- Any Linux: download the binary from the releases page and make it executable
- Docker: run ctop as a container without installing it on the host
brew install ctopCheck the requirements before you start
ctop needs Docker or runC on the host, so there are containers to monitor. It has built-in support for those two systems. The README says connectors for other container and cluster systems are planned for future releases, but it does not list them as available now.
- Docker or runC installed and running on the host
- Access to the Docker socket if you run ctop with its default setup
- No arguments are required to start ctop
Run ctop with Docker instead of a local install
If you do not want to install a binary, the README shows a way to run ctop as a container. The command mounts the Docker socket read-only so ctop can read container information. The image is listed at quay.io/vektorlab/ctop.
- --rm removes the container when you exit
- -ti gives the container an interactive terminal
- --volume mounts /var/run/docker.sock read-only (the :ro flag)
docker run --rm -ti --name=ctop --volume /var/run/docker.sock:/var/run/docker.sock:ro quay.io/vektorlab/ctop:latestLearn the main screen and keybindings
The main screen shows a condensed overview of multiple containers. Use the keys below to change what you see. Press q to quit.
- Enter: open the container menu
- a: toggle display of all running and non-running containers
- f: filter displayed containers (press esc to clear the filter when it is open)
- s: select the container sort field
- r: reverse the sort order
- H: toggle the ctop header
- h: open the help dialog
- c: configure columns
- o: open the single container view
- l: view container logs (press t to toggle timestamps)
- e: open a shell in the container
- S: save the current configuration to a file
- q: quit ctop
Use startup options and the config file
ctop accepts a few command-line options. You can set a starting filter, a sort field, or show only active containers. When you press S while ctop is running, it saves the current filters, sort field and other options to a default config file, which is loaded the next time you start ctop.
- -a: show active containers only
- -f <string>: set an initial filter string
- -s: select an initial sort field
- -r: reverse container sort order
- -i: invert default colors
- -v: print version information and exit
- -h: display the help dialog
- Config file: ~/.config/ctop/config on XDG systems, otherwise ~/.ctop
ctop -a -f webInspect one container in the single view
The single container view gives a closer look at one container. Select a container in the main list and press o to open it. From the main screen you can also press Enter to open the container menu, or use l and e for logs and shell access.
- Open the single view with o
- View logs with l, and press t inside the logs to show timestamps
- Open a shell with e
What people use it for
- Watching resource use across several local Docker containers while you develop
- Checking which containers are running or stopped with the a toggle and filters
- Reading container logs with timestamps from the same screen
- Opening a shell in a misbehaving container without typing a separate docker exec command
- Running ctop on a server over a terminal session to check container health
Frequently asked questions
Is ctop free to use?
Yes. ctop is open source and released under the MIT licence, according to the project page. You can use it, including in work settings, under the terms of that licence.
What do I need to run ctop?
You need Docker or runC on the host, so there are containers to monitor. ctop has built-in support for those two systems and needs no arguments to start.
How do I install ctop on Mac or Windows?
On macOS, use brew install ctop with Homebrew. On Windows, use scoop install ctop with scoop. You can also download the binary from the releases page.
Why does ctop show no containers or only some containers?
By default you may see only running containers. Press a to toggle display of all running and non-running containers. You can also check that your filter with f is not hiding containers, and press esc to clear it.
Does ctop work with Kubernetes or other container platforms?
The README says ctop has built-in support for Docker and runC only. Connectors for other container and cluster systems are planned for future releases, so they are not available now.
How does ctop compare to Docker stats, lazydocker and Portainer?
The project lists Docker stats, lazydocker and Portainer as comparable projects. ctop is a terminal tool that shows live metrics for many containers, with a single view and shortcuts for logs and shell access. The README does not describe long-term history or alerting, so pick a tool that offers those if you need them.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
ctop suits developers and operators who run Docker or runC containers locally or on a server and want a fast, live terminal overview with logs and shell access one key away. If you need long-term metric history, alerting, a graphical web interface, or support for platforms other than Docker and runC, look at a different tool such as Portainer or a monitoring stack.
Install options & downloads