INTERACTIVE TUTORIAL

Master btop
the modern
resource monitor

btop++ is a beautiful, feature-rich terminal resource monitor written in C++. This interactive guide will take you from installation to advanced usage, with live simulations and hands-on practice.

30.5k
GitHub Stars
C++
Language
v1.4.6
Latest Version
14
Lessons
[ cpu ] [ mem ] [ net ] [ proc ]12:23:27 PM — 2000ms
┌─ cpu ─────────────────────────────────────────────────────────────────────────────────────────────────────┐
CPU History
▂▃▃▃▃▄▄▃▄▃▃▄
Total: 35.0% Freq: 3.6GHz Temp: 52°C
Per Core
C0██▏░░░░░░░28%
C1███▏░░░░░░42%
C2█▏░░░░░░░░19%
C3█████▏░░░░55%
C4██▏░░░░░░░31%
C5████▏░░░░░48%
C6█▏░░░░░░░░22%
C7███▏░░░░░░38%
Load avg:
0.82 0.74 0.68
Uptime:
3d 14:22:08
┌─ mem ──────────────────────────────────────┐
Total: 16 GiB
Used████████▏░░░░░░░░░8.4G
Free████████▏░░░░░░░░░7.6G
Swap░░░░░░░░░░░░░░░░░░0.2G
┌─ net ──────────────────────────────────────┐
eth0
↓ ▁▂▁▂▃▃▄▄▅▄▅▅
↓ 1.2 MiB/s
↑ 0.4 MiB/s
Disk R: 12.5 MB/s W: 4.2 MB/s
┌─ proc ─filter─tree─cpu lazy──────────────────────────────────────┐
PIDProgramUserCPU%Mem%Threads
1842firefoxuser
██▏░░░░░░░░░12.4
8.2%42
3291codeuser
█▏░░░░░░░░░░8.1
5.6%28
892systemdroot
▏░░░░░░░░░░░2.3
0.4%8
4521nodeuser
▏░░░░░░░░░░░5.7
3.1%12
1203Xorgroot
░░░░░░░░░░░░1.8
1.2%4
7834python3user
▏░░░░░░░░░░░3.2
2.8%6
↑↓ select Enter details f filter k kill e tree q quit
02

Installation

Get btop running on your system in under a minute

PACKAGE MANAGERS

Debian / Ubuntu / Mint$ sudo apt install btop
Fedora / RHEL / CentOS$ sudo dnf install btop
Arch Linux / Manjaro$ sudo pacman -S btop
openSUSE$ sudo zypper install btop
Alpine Linux$ sudo apk add btop
macOS (Homebrew)$ brew install btop
FreeBSD$ sudo pkg install btop
Snap (Universal)$ sudo snap install btop

BUILD FROM SOURCE

bash
# Clone the repository
$ git clone https://github.com/aristocratos/btop.git
$ cd btop
# Compile (requires GCC 10+ or Clang 12+)
$ make
# Install to /usr/local/bin
$ sudo make install
# Optional: enable GPU monitoring (Linux)
$ make GPU_SUPPORT=true
▸ REQUIREMENTS
GCC 10+ or Clang 12+ compiler
GNU Make
UTF-8 locale configured
Terminal with 24-bit truecolor support
Font with Braille Unicode support (for graphs)

LAUNCH BTOP

bash
# Basic launch
$ btop
# Start with a specific preset (0-9)
$ btop -p 1
# Set update interval (milliseconds)
$ btop -u 1000
# Start with process filter
$ btop -f firefox
# Force low-color mode (256 colors)
$ btop -l
03

Interface Tour

Explore each panel of the btop interface

btop++ v1.4.6
─ cpu ─────────────────────────────────────35%
▃▄▅▄▃▂▂▂▃▅▅▄C0:28% C1:42% C2:19% C3:55%
Freq: 3.6GHz Temp: 52°C Uptime: 3d 14:22
─ mem ──────────────────
Used: 8.4/16 GiB
Swap: 0.2/8 GiB
Disk R: 12.5 MB/s
─ net ──────────────────
▄▅▆▅▄▃▃▃▄▅▆▅
↓ 1.2 MiB/s ↑ 0.4 MiB/s
─ proc ─ filter ─ tree ─ cpu lazy ──────────
PIDProgramUserCPU%Mem%
1842firefoxuser12.4%8.2%
3291codeuser8.1%5.6%
4521nodeuser5.7%3.1%
CPU Panel

The CPU panel occupies the top portion of the btop interface and provides a comprehensive view of processor activity.

▸Overall CPU usage percentage with color-coded graph (green → amber → red)
▸Historical usage graph using braille characters for high resolution
▸Per-core usage bars showing individual thread load
▸CPU frequency and temperature (if sensors are available)
▸Load average (1, 5, 15 minute averages)
▸System uptime displayed in the corner

Click any panel in the interface diagram above to learn about it

05

Key Bindings

Complete reference for all btop keyboard shortcuts

btop keyboard shortcuts visualization

APPLICATION

mEsc
Main Menu
Opens the main menu with Options, Help, and Quit
oF2
Options
Open the settings and configuration menu
hF1
Help
Show the help screen with all key bindings
qCtrl+C
Quit
Exit btop
+
Slower Updates
Add 100ms to the update interval
-
Faster Updates
Subtract 100ms from the update interval

PROCESS MANAGEMENT

k
Kill (SIGTERM)
Send SIGTERM to the selected process (graceful stop)
K
Force Kill (SIGKILL)
Send SIGKILL — immediately terminates the process
i
Interrupt (SIGINT)
Send SIGINT to the selected process
t
Stop (SIGSTOP)
Pause/suspend the selected process
s
Send Signal
Open menu to send any signal to the process
Enter
Process Details
View detailed stats for the selected process

DISPLAY & FILTER

f/
Filter Processes
Type to filter the process list in real-time
e
Toggle Tree View
Show processes as a parent-child tree
r
Reverse Sort
Reverse the current sorting order
bn
Network Interface
Switch to previous/next network interface
p
Toggle Pause
Pause the process list from updating
1-9
Select Preset
Switch to a saved layout preset (1-9)
06

Customization

Themes, presets, and configuration options

THE OPTIONS MENU

Press o or F2 to open the Options menu. Every setting is configurable from within the UI — no need to manually edit config files.

Color Theme
Choose from built-in themes or create custom ones. Themes are stored in ~/.config/btop/themes/
Graph Symbols
Select between braille (highest res), block, or tty symbols for graphs
Update Interval
Set how often btop refreshes data (default: 2000ms)
Process Sorting
Default sort column: cpu lazy, cpu direct, pid, memory, user, etc.
Vim Keys
Enable h/j/k/l navigation for keyboard-centric users
Shown Boxes
Toggle which panels are visible: cpu, mem, net, proc, gpu0-5

CONFIGURATION FILE

The config file is auto-generated at ~/.config/btop/btop.conf. All changes made in the Options menu are saved here automatically.

btop.conf
# Color theme (Default, TTY, or custom theme name)
color_theme = "Default"
# Graph symbol style: braille, block, or tty
graph_symbol = "braille"
# Update interval in milliseconds
update_ms = 2000
# Default process sort column
proc_sorting = "cpu lazy"
# Show processes as tree by default
proc_tree = false
# Enable vim-style navigation keys
vim_keys = false
# Which panels to show
shown_boxes = "cpu mem net proc"
# Show CPU temperature
check_temp = true
# Temperature scale: celsius, fahrenheit, kelvin
temp_scale = "celsius"
# Auto-scale network graphs
net_auto = true

PRESETS

Presets let you save different panel layouts and switch between them with number keys 1-9. Preset 0 always shows all panels with default settings.

btop.conf
# Preset format: "box:position:graph_symbol"
# Multiple presets separated by spaces
presets = "cpu:1:default,proc:0:default cpu:0:default,mem:0:default,net:0:default cpu:0:block,net:0:tty"
# Switch presets with keys 1, 2, 3...
# Preset 0 = all boxes, default settings
07

GPU Monitoring

Track graphics card usage, VRAM, temperature, and clock speeds

btop++GPU Monitoring
─ gpu0 ─ AMD Radeon RX 7800 XTDriver: amdgpu 6.6
GPU Usage History
▄▃▂▃▃▂▃▂▂▃▂▅▅▂▂▄▅▃▁▁
████████████29%
VRAM
Used2.7 / 16 GiB
████████████17%
Power Draw
Draw113W / 263W
████████████43%
Temperature History
▄▅▄▅▄▅▅▅▄▄▅▅▄▅▄▅▄▅▃▄
Core Temp53°C
Clock Speeds
Core2404 MHz
Memory19757 MHz
Fan1473 RPM
PCIe Info
Slot: PCIe 4.0 x16
VRAM Type: GDDR6
Compute: ROCm 5.7
↑↓ selectEnterdetailsffilterqquit

ENABLING GPU MONITORING

btop supports GPU monitoring for NVIDIA (via nvidia-smi) and AMD (via amdgpu) cards. You must compile btop with GPU_SUPPORT=true or install a package that includes it.

bash
# Compile with GPU support
git clone https://github.com/aristocratos/btop.git
cd btop
make GPU_SUPPORT=true
sudo make install
# Or install the Flatpak (includes GPU support)
flatpak install flathub app.btop.btop

GPU PANEL METRICS

GPU Usage %Overall shader/compute utilization with color-coded bar (green → amber → red)
VRAMVideo memory used vs. total — critical for gaming and ML workloads
TemperatureCore temperature with history graph; alerts at high values
Core ClockCurrent GPU core frequency in MHz — drops when idle or throttling
Memory ClockVRAM bus speed — GDDR6X can exceed 20,000 MHz effective
Fan RPMCooling fan speed — correlates with temperature and load
Power DrawWatts consumed vs. TDP power limit — useful for efficiency tuning
▸ GPU KEYBOARD SHORTCUTS
gToggle GPU panel visibility
oOptions → Shown boxes → toggle gpu0–gpu5
1-9Switch presets — create GPU-only or GPU+CPU layouts
08

Theme Gallery

Explore built-in and community themes with live preview

8 themes
✓ active
Default
Built-in
TTY
Built-in
Dracula
Community
Nord
Community
Gruvbox Dark
Community
Solarized Dark
Community
Catppuccin Mocha
Community
Tokyo Night
Community
DefaultBuilt-in

The classic btop theme — dark background with vibrant multi-color accents

[ cpu ] [ mem ] [ net ] [ proc ]10:07:21 AM
─ cpu ──██████████42%
─ mem ──██████████8.4G
─ net ──██████████↓1.2M
─ proc ─ filter ─ tree
PIDProgramCPU%
1842firefox12.4%
3291code8.1%
▸ ACTIVATE DEFAULT THEME
1. Launch btop and press o or F2 to open Options
2. Navigate to Color theme
3. Select Default from the list
4. Press Esc to close Options
09

Troubleshooting

Solutions to the most common btop issues

10

Process Signals

Understand UNIX signals — what they do, when to use them, and how btop sends them

ℹ

In btop, the k, K, t, and i keys send UNIX signals to the selected process. Understanding what each signal does helps you make the right choice when managing processes. Click any signal card below to explore its behavior, use cases, and relationship to btop controls.

Termination
Interruption
Control
User-Defined
k
btop key
SIGTERM
Signal #15 · Termination
catchableignorable
btop key:k
DESCRIPTION

Terminate — the standard, polite termination request. Gives the process a chance to clean up before exiting.

DEFAULT BEHAVIOR

Default action is to terminate. Well-behaved processes catch this to flush buffers, close files, and release locks.

WHEN TO USE

The correct first choice for stopping any process. This is what btop sends when you press k.

EXAMPLE
# In btop: select process → press k (kill)
▸ RECOMMENDED KILL SEQUENCE
1.kSIGTERMPolite request — wait 5–10s
2.kSIGTERMRetry if still running
3.KSIGKILLForce kill as last resort
11

Command Builder

Compose your perfect btop launch command interactively — then copy and run it

-lForce 256-color mode
-UForce UTF-8 locale
--no-rm-cacheKeep process cache
--ttyTTY mode (ASCII only)
-dEnable debug logging
$btop
Select options on the left to build your command
▸
Tip: You can also change most of these settings inside btop itself. Press o to open Options, or use +/- to adjust update speed on the fly.
12

Key Drill

Practice mode — read the action, press the right key. Build muscle memory fast.

KEY DRILL MODE

You'll be shown an action description. Press the correct key as fast as you can. Immediate feedback — no multiple choice, just muscle memory.

CATEGORY
17 questions
13

History & Comparison

From bashtop to bpytop to btop++ — the evolution, and how it stacks up against htop

2019
◎ bashtop v0.x
The Origin: bashtop

aristocratos wrote the first version entirely in Bash. It worked but was slow — pure shell script parsing /proc files. It proved the concept of a beautiful, colorful resource monitor but had serious performance limits.

Written in BashColorful TUI with braille graphsProof of conceptSlow on high process counts
2021
🐍 bpytop v1.x
The Rewrite: bpytop

The project was rewritten in Python 3 as bpytop, dramatically improving performance and adding features. This version gained widespread adoption and was packaged in most Linux distributions.

Python 3 rewriteMuch faster than bashtopAdded mouse supportPackaged in major distrospsutil for cross-platform stats
2021
⚡ btop++ v1.0
The C++ Era: btop++

A full C++ rewrite for maximum performance. Zero Python/Bash overhead. Native threading, direct /proc parsing on Linux, and a custom TUI framework. The '++' in the name signals the language shift.

C++17 rewriteNear-zero CPU overheadCustom TUI rendererDirect /proc parsingmacOS and FreeBSD support
2022
★ btop++ v1.2
Maturity: Themes & Presets

Added the full theme system with community theme support, the preset layout system (keys 1-9), improved graph rendering, and significantly expanded configuration options.

Full theme systemPreset layouts (1-9)Improved graph qualityExpanded config optionsCommunity theme support
2023
▣ btop++ v1.3
GPU Monitoring

The most-requested feature arrived: GPU monitoring for NVIDIA and AMD cards. Requires compiling with GPU_SUPPORT=true or using the Flatpak. Tracks usage, VRAM, temperature, clocks, fan, and power.

NVIDIA GPU supportAMD GPU support (amdgpu)VRAM monitoringGPU temperature graphsPower draw tracking
2024
★ btop++ v1.4
Polish & Performance

Continued refinement: improved battery monitoring, better macOS support, Intel GPU support added, performance optimizations for systems with thousands of processes, and many bug fixes.

Intel GPU supportImproved battery statsBetter macOS supportHigh process-count optimizationsNumerous bug fixes
14

Test Your Knowledge

Interactive quiz to reinforce what you've learned

Key Binding Quiz
Q 1/10Score 0
What does pressing 'f' or '/' do?
f

QUICK REFERENCE CARD

Essential Key Bindings — Quick Reference
qQuit
hHelp
oOptions
mMenu
fFilter
eTree view
rReverse sort
kKill process
KForce kill
EnterDetails
+/-Update speed
b/nNetwork iface
1-9Presets
pPause list
▸ NEXT STEPS
▸Explore the Options menu (press o) to customize your setup
▸Try enabling tree view (e) to understand process hierarchies
▸Create custom presets for different monitoring scenarios
▸Install a custom theme from the btop themes directory
▸Enable GPU monitoring if you have a compatible GPU