vtop: How to Install and Use It on Mac and Linux
vtop is a graphical activity monitor for the terminal. It draws CPU and memory history as dotted graphs made of Unicode braille characters, and it lists your processes grouped by name. It is written in JavaScript, so you install it with npm:
npm install -g vtop
vtop
Press q to quit. That's the whole install if you already have Node.js. The rest of this guide covers installing on each OS, the keyboard shortcuts, themes and options, and fixes for the errors you're most likely to hit.
What vtop Shows
The screen has three parts:
- CPU Usage: a scrolling graph of total CPU load across all cores.
- Memory Usage: a scrolling graph of used memory.
- Process List: processes grouped by name, with their combined CPU and memory share. Several copies of the same program show up as one row. The CPU column counts 100% as every core maxed out, so it reads lower than Activity Monitor's %CPU column on a Mac, where one busy core alone is 100%.
The header shows your hostname, the time, and the load average. The footer lists the main keys.
How to Install vtop
vtop needs Node.js, and any version from Node 4 up satisfies its engines field. The current release is 0.6.1, published in September 2018, and it hasn't changed since. It still runs: I tested 0.6.1 on Node 24 on macOS while writing this.
macOS
Homebrew doesn't have a vtop formula (brew install vtop fails and suggests nvtop, which is a GPU monitor). Install Node.js, then vtop through npm:
brew install node
npm install -g vtop
vtop
If you use nvm to manage Node, the same npm install -g vtop works without sudo.
Linux
Install Node.js from your distribution or with nvm, then install vtop the same way:
# Debian and Ubuntu
sudo apt install nodejs npm
npm install -g vtop
vtop
With the system Node, npm install -g writes to a root-owned directory, so you may need sudo npm install -g vtop. With nvm you don't. vtop reads processes through ps, reads memory with free, and kills processes with killall. If killall is missing, install psmisc.
Try It Without Installing
To run vtop once without a global install:
npx vtop
Make It Your Default top
vtop's README suggests aliasing it over top. Add this to ~/.zshrc or ~/.bashrc:
alias top="vtop"
alias oldtop="/usr/bin/top"
vtop Keyboard Shortcuts
| Key | Action |
|---|---|
q, Esc, Ctrl+C | Quit |
j or ↓ | Move down the process list |
k or ↑ | Move up the process list |
g | Jump to the top of the list |
G | Jump to the bottom of the list |
c | Sort by CPU |
m | Sort by memory |
h or ← | Zoom the graphs in |
l or → | Zoom the graphs out |
dd | Kill every process with the selected name |
u | Upgrade vtop (runs sudo npm install -g vtop) |
Be careful with dd. It runs killall "<name>" on the selected row, with no confirmation. Because rows are grouped by name, it kills every process with that name, not just one. Pressing dd on node stops every Node process you own.
Skip u if you installed Node with nvm, since it upgrades with sudo. Run npm install -g vtop yourself instead.
If your terminal sends mouse events, such as iTerm2, you can click rows and scroll the process list with the mouse.
Themes and Options
vtop ships 12 themes: acid, becca, brew, certs, dark, gooey, gruvbox, monokai, nord, parallax, seti, and wizard. Pick one with --theme:
vtop --theme nord
To use a theme every time, put it in an alias:
alias vtop="vtop --theme nord"
The other options, from vtop --help:
| Option | What it does |
|---|---|
-t, --theme [name] | Use a theme |
--no-mouse | Turn off mouse handling |
--update-interval [milliseconds] | Set how often the screen redraws |
--quit-after [seconds] | Exit automatically after that many seconds |
-V, --version | Print the version |
Troubleshooting
command not found: vtop after installing. npm's global bin directory isn't on your PATH. Find it and add it:
npm prefix -g
# add "<that path>/bin" to PATH in ~/.zshrc or ~/.bashrc
EACCES: permission denied during npm install -g. Your global npm directory is owned by root. Either install Node with nvm, which keeps global packages in your home directory, or run sudo npm install -g vtop. Don't use sudo if you're on nvm.
The graphs show boxes or question marks. Your terminal font doesn't have braille characters. Switch to a font that includes the Unicode braille block.
dd doesn't kill the process. killall can only signal processes you own. Processes run by root or another user stay up unless you started vtop with sudo.
A process's CPU % looks too low. The process list divides by the number of cores, so on an 8-core Mac one core at 100% shows as about 12.5%.
To uninstall:
npm uninstall -g vtop
A Lighter vtop
vtop runs inside Node.js, so the monitor itself holds a lot of memory: 112–124 MiB across my benchmarks. I liked the interface enough that I rebuilt it in Rust as ptop, with the same dots, grouping, keys, and themes. In a matched test on my M2 Max, ptop used about 73% less CPU and 92% less own-process memory than vtop 0.6.1. The ptop write-up has the benchmark and install steps. On Apple Silicon Macs running macOS 15 or later:
npm install -g @patebryant/ptop
ptop
If you're still choosing a monitor, I also compared htop, btop, vtop, and ptop side by side.