When Debian’s built-in top view feels too cramped for real troubleshooting, install htop on Debian to get a scrollable process list, per-core CPU meters, memory and swap usage, search, filtering, tree view, mouse support, and easier process actions from one terminal screen. Debian ships htop in its default APT repositories, while upstream also publishes source releases for users who want a manually managed newer build.
Use the APT package for the lowest-maintenance setup on Debian 13, Debian 12, or Debian 11. Use the manual GitHub source method only when you specifically need the current upstream release in your home directory and accept that APT will not update or remove that build.
Install htop on Debian
Check Whether htop Is Already Installed
On reused desktops and servers, confirm the active htop command before installing another copy:
command -v htop && htop --versionIf command -v htop prints no path, continue with one of the installation methods. If it prints a path, note whether the command comes from /usr/bin/htop, a home-directory path such as ~/.local/bin/htop, or another custom location.
Update Debian Packages
Refresh APT metadata before installing htop so Debian uses current package indexes from the repositories already enabled on your system:
sudo apt updateThese commands use
sudofor package-management tasks. If your account cannot use sudo, configure administrative access first by adding a user to sudoers on Debian.
Choose an htop Installation Method
Debian has two practical htop paths. APT is recommended because it uses Debian’s package database, dependency handling, security updates, and normal removal workflow. The manual source method builds upstream htop under your home directory and is useful only when the Debian-packaged version is not the one you want to run.
| Method | Source | Update Owner | Best Fit | Trade-Offs |
|---|---|---|---|---|
| APT (recommended) | Debian repositories | Debian package updates through APT | Most Debian desktops, servers, containers, and scripts | Version follows the Debian release instead of the newest upstream tag |
| Manual source | GitHub Releases | Local helper rerun by the user | Advanced users who need the current upstream release in ~/.local | Build dependencies required; outside APT install, update, and removal ownership |
Debian 13 (Trixie) currently provides htop 3.4.x, Debian 12 (Bookworm) provides 3.2.x, and Debian 11 (Bullseye) provides 3.0.x. Upstream’s current GitHub release is 3.5.1, so the manual method is mainly a version-choice path, not a normal Debian requirement.
Use one htop method for everyday use. If both the APT package and a source build exist, your shell runs whichever
htopappears first onPATH. Recheck withcommand -v htopafter installing or removing a method.
Install htop with APT
Install the Debian package named htop:
sudo apt install htopVerify that Debian installed the package and that the command is available:
dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package} ${Version}\n' htop
htop --versionii htop 3.4.1-5 htop 3.4.1
The exact version depends on your Debian release. On Debian 13, the package version currently reports htop 3.4.1. On Debian 12, expect htop 3.2.2. On Debian 11, expect htop 3.0.5. The core monitoring, sorting, filtering, and process-control workflow works across these 3.x releases.
If you meant the classic top command instead of htop, Debian normally provides top through the procps package. Run top directly, or continue with htop when you want the enhanced interactive viewer.
The Debian htop package suggests optional helpers:
lm-sensorsfor temperature sensor data,lsoffor open-file inspection, andstracefor system call tracing. Install only the helpers you need; htop itself works without them.
Build htop from GitHub Source
The manual source method installs htop under ~/.local/opt/htop and exposes ~/.local/bin/htop. It does not overwrite Debian’s /usr/bin/htop, but it can take precedence when ~/.local/bin comes before /usr/bin on PATH.
Install Source Build Dependencies
Install the compiler, autotools, JSON parser, download tool, certificate bundle, and common htop feature libraries:
sudo apt install curl jq build-essential autoconf automake autotools-dev pkg-config libncurses-dev libcap-dev libsensors-dev libnl-3-dev libnl-genl-3-dev ca-certificatesThe libncurses-dev package supplies the wide-character ncurses headers used by current Debian releases. Some upstream examples still mention libncursesw5-dev, but libncurses-dev is the release-safe package name for Debian 13, Debian 12, and Debian 11.
Create the htop Source Update Helper
Create a reusable update-htop-source helper. With no argument, it resolves the latest stable GitHub release through the GitHub API. With a version argument, it builds that exact release tag, which is useful when you want to repeat a tested version. The helper also checks the release metadata for the expected source tarball and checksum asset before it downloads anything.
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > "$HOME/.local/bin/update-htop-source" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
RELEASE_API="https://api.github.com/repos/htop-dev/htop/releases/latest"
TAG_API="https://api.github.com/repos/htop-dev/htop/releases/tags"
WORKDIR="${HTOP_SOURCE_WORKDIR:-$HOME/htop-source-build}"
PREFIX_BASE="${HTOP_PREFIX_BASE:-$HOME/.local/opt/htop}"
BIN_DIR="${HTOP_BIN_DIR:-$HOME/.local/bin}"
TAG="${1:-}"
if [ -n "$TAG" ] && ! [[ "$TAG" =~ ^[0-9]+[.][0-9]+[.][0-9]+$ ]]; then
echo "Use an htop release tag such as 3.5.1."
exit 1
fi
if [ -z "$TAG" ]; then
RELEASE_JSON=$(curl -fsSL "$RELEASE_API")
TAG=$(jq -r 'select(.draft == false and .prerelease == false) | .tag_name // empty' <<<"$RELEASE_JSON")
else
RELEASE_JSON=$(curl -fsSL "${TAG_API}/${TAG}")
fi
if ! [[ "$TAG" =~ ^[0-9]+[.][0-9]+[.][0-9]+$ ]]; then
echo "Could not resolve a stable htop release tag."
exit 1
fi
ARCHIVE="htop-${TAG}.tar.xz"
SHA_FILE="${ARCHIVE}.sha256"
ARCHIVE_URL=$(jq -r --arg name "$ARCHIVE" '.assets[]? | select(.name == $name) | .browser_download_url' <<<"$RELEASE_JSON")
SHA_URL=$(jq -r --arg name "$SHA_FILE" '.assets[]? | select(.name == $name) | .browser_download_url' <<<"$RELEASE_JSON")
LINK="${BIN_DIR}/htop"
OWNED_TARGET="${PREFIX_BASE}/current/bin/htop"
if [ -z "$ARCHIVE_URL" ] || [ -z "$SHA_URL" ]; then
echo "Release ${TAG} does not publish the expected htop source assets."
exit 1
fi
mkdir -p "$WORKDIR" "$PREFIX_BASE" "$BIN_DIR"
need_build=yes
if [ -x "$PREFIX_BASE/current/bin/htop" ]; then
VERSION_LINE=$("$PREFIX_BASE/current/bin/htop" --version | head -n 1 || true)
INSTALLED_VERSION=${VERSION_LINE#htop }
INSTALLED_TAG=${INSTALLED_VERSION%%-*}
if [ "$INSTALLED_TAG" = "$TAG" ]; then
need_build=no
fi
fi
if [ "$need_build" = yes ]; then
cd "$WORKDIR"
rm -rf "htop-${TAG}" "$ARCHIVE" "$SHA_FILE"
curl -fL --progress-bar -o "$ARCHIVE" "$ARCHIVE_URL"
curl -fL --progress-bar -o "$SHA_FILE" "$SHA_URL"
sha256sum -c "$SHA_FILE"
tar -xf "$ARCHIVE"
cd "htop-${TAG}"
./configure --prefix="${PREFIX_BASE}/${TAG}"
make -j"$(nproc)"
make install
ln -sfnT "${PREFIX_BASE}/${TAG}" "${PREFIX_BASE}/current"
else
echo "htop ${TAG} is already installed at ${PREFIX_BASE}/current."
fi
if [ -e "$LINK" ] || [ -L "$LINK" ]; then
if [ ! -L "$LINK" ]; then
echo "Refusing to replace existing non-symlink: $LINK"
exit 1
fi
CURRENT_TARGET=$(readlink "$LINK")
case "$CURRENT_TARGET" in
"$OWNED_TARGET"|"${PREFIX_BASE}"/*/bin/htop) ;;
*)
echo "Refusing to replace existing htop symlink: $LINK -> $CURRENT_TARGET"
exit 1
;;
esac
fi
ln -sfnT "$OWNED_TARGET" "$LINK"
"$LINK" --version | head -n 1
EOF
chmod +x "$HOME/.local/bin/update-htop-source"
bash -n "$HOME/.local/bin/update-htop-source"The helper resolves the release, confirms that GitHub lists both the release tarball and its .sha256 sidecar, verifies the checksum with sha256sum -c, compiles htop, installs the result into a versioned directory, and then updates the current and htop symlinks. It refuses to replace an unrelated non-symlink or a symlink that points outside the managed htop source prefix.
Build the Tested GitHub Release
Run the helper with the currently tested upstream release tag:
update-htop-source 3.5.1Relevant success lines include the checksum result and the compiled htop version:
htop-3.5.1.tar.xz: OK htop 3.5.1-3.5.1
After the build, command -v htop should point to ~/.local/bin/htop when that directory appears before /usr/bin on PATH. If the command still resolves to /usr/bin/htop, the Debian package is still taking precedence in the current shell.
For future updates after dependencies are installed, run the helper without a version argument to build the latest stable GitHub release:
update-htop-sourceIf the selected release is already installed, the helper prints an already installed message and exits without rebuilding.
Use htop on Debian
Start htop from any terminal:
htopTo monitor only your own processes, launch htop with a user filter:
htop -u "$USER"
Read the htop Screen
The top area shows CPU meters, memory usage, swap usage, load averages, task counts, uptime, and other meters that depend on your configuration. Under the meters, the process list shows one running task per row with columns such as PID, user, priority, nice value, memory, CPU percentage, elapsed time, and command.
The colors are hints, not separate commands. CPU meters divide time across user, system, nice, and other states. Memory meters separate used memory from buffers and cache. On servers with many services, sorting by CPU or memory usually gives the fastest answer to “what is busy right now?”
Htop can show process-level I/O columns when you enable them in the setup menu, but it is not a full network bandwidth dashboard. Use htop to identify busy processes; use network-specific tools when you need per-interface traffic, packet captures, or connection-level detail.
Navigate and Sort Processes
Use arrow keys, function keys, or the mouse to move around the process list and change sort order:
| Key or Action | What It Does |
|---|---|
| Up/Down | Move through the process list |
| Left/Right | Scroll horizontally to view more columns |
| F6 | Open the sort menu for CPU, memory, PID, time, and other columns |
| F5 | Toggle tree view to show parent-child process relationships |
| Mouse click on a column | Sort by that column when your terminal passes mouse events to htop |
Search and Filter Processes
Search highlights matching processes, while filtering hides nonmatching rows until the filter is cleared:
| Key | Action | Example Use |
|---|---|---|
F3 or / | Search the process list | Find the next process with nginx, ssh, or a service name in the command line |
F4 or \ | Filter the process list | Show only rows matching your username, a service account, or a command fragment |
| Esc | Leave a menu, search, or filter prompt | Return to the live process list without exiting htop |
Control Processes Safely
Htop can send signals and adjust nice values from inside the interface. Use these actions carefully on production systems because they can stop services or change scheduling behavior immediately.
| Key | Action | Safer Starting Point |
|---|---|---|
F9 or k | Send a signal to the selected process | Use SIGTERM (15) first so the process can exit cleanly |
| F9 then SIGKILL (9) | Force immediate termination | Use only when SIGTERM does not work and you understand the data-loss risk |
| F7 | Increase priority by lowering the nice value | Usually requires elevated privileges for other users’ processes |
| F8 | Decrease priority by raising the nice value | Useful for throttling background jobs that compete with interactive work |
Regular users can manage only their own processes within normal permission limits. Start htop with sudo htop only when you need to inspect or manage system-owned processes.
Customize the Display
Press F2 to open the setup menu. Htop saves per-user settings in ~/.config/htop/htoprc, so meter layout, color schemes, and selected columns persist across later sessions for the same account.
- Add or rearrange meters such as CPU, memory, swap, load average, uptime, battery, or temperature where available.
- Move columns that matter for your workflow, such as CPU percentage, memory percentage, I/O columns, PID, PPID, nice value, or command.
- Switch color schemes if the default palette is hard to read in a light, dark, or remote terminal.
Press F10 or Q to exit htop and return to the shell prompt.
htop Command-Line Options
Htop is mainly interactive, but several command-line flags help you start in the view you need.
Start with Tree View
Show parent-child process relationships immediately:
htop -tSort by CPU or Memory
Start with the highest CPU users at the top:
htop -s PERCENT_CPUStart with the highest memory users at the top:
htop -s PERCENT_MEMMonitor Specific Users or Processes
Show only processes owned by a specific user:
htop -u www-dataShow only selected process IDs:
htop -p 1234,5678Replace the example values with a real username or PID list. To find PIDs first, use tools such as pgrep, pidof, or ps.
Adjust Refresh Rate or Terminal Behavior
The -d flag sets the refresh delay in tenths of a second. This example refreshes every 3 seconds:
htop -d 30A slower refresh rate can reduce CPU overhead on small virtual machines, low-power hardware, or busy servers. Disable mouse handling or color output when a remote terminal does not render htop cleanly:
htop --no-mouse
htop --no-colorUpdate htop on Debian
Update htop with the same method used for installation. Mixing update paths can leave multiple htop binaries on the same account.
Update APT htop
APT updates the Debian package when a newer build appears in your configured Debian repositories:
sudo apt update
sudo apt install --only-upgrade htopFor normal system maintenance, sudo apt upgrade also upgrades htop alongside the rest of your installed Debian packages.
Update Source-Built htop
The manual helper checks the latest stable GitHub release, downloads the matching tarball and checksum file, rebuilds htop, and updates your home-directory symlinks:
update-htop-sourceIf you want to stay on a known release, pass the version tag instead:
update-htop-source 3.5.1Uninstall htop from Debian
Remove htop with the same method used for installation. If you are unsure which command is active, check the path first:
command -v htopRemove APT htop
If you installed htop with APT, remove the Debian package:
sudo apt remove htopVerify that the package is no longer installed:
dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' htop 2>/dev/null | grep '^ii' || echo "htop is not installed"htop is not installed
Preview unused dependency cleanup separately before removing anything else:
sudo apt autoremove --dry-runIf the preview lists only packages you no longer need, run sudo apt autoremove interactively and review the final prompt before accepting the transaction.
Remove Source-Built htop
The manual method creates files under your home directory. Remove the source workspace, versioned install tree, helper, and managed command symlink:
The next block permanently deletes the source-build workspace and managed htop install tree for the current user. Keep any custom build logs or local changes before running it.
if [ -L "$HOME/.local/bin/htop" ] && [ "$(readlink "$HOME/.local/bin/htop")" = "$HOME/.local/opt/htop/current/bin/htop" ]; then
rm -f "$HOME/.local/bin/htop"
elif [ -e "$HOME/.local/bin/htop" ]; then
echo "Review $HOME/.local/bin/htop manually; it is not the managed htop source-build symlink."
fi
rm -rf "$HOME/htop-source-build" "$HOME/.local/opt/htop"
rm -f "$HOME/.local/bin/update-htop-source"
hash -rConfirm whether another htop method remains on your command path:
command -v htopIf this still prints a path, the APT package or another custom htop binary remains installed.
Remove Personal htop Settings
APT removal and source-build cleanup do not delete your per-user htop layout file. Remove it only when you want to reset custom meters, columns, colors, and saved settings for the current account.
The next command permanently removes the current user’s htop settings. Skip it if you want to keep your saved layout for a future reinstall.
rm -rf "$HOME/.config/htop"Troubleshoot htop on Debian
htop Command Not Found
If Bash, Zsh, or another shell reports htop: command not found, install the APT package or fix the PATH for the source-built command.
sudo apt update
sudo apt install htopIf the package was just installed and the same shell still reports the old result, clear Bash’s command cache or open a new terminal:
hash -r
command -v htopFor the manual source method, make sure ~/.local/bin is visible in the current shell:
export PATH="$HOME/.local/bin:$PATH"
hash -r
command -v htopAPT Cannot Locate the htop Package
If APT cannot find htop, the package index may be stale or the system may be using incomplete Debian sources:
E: Unable to locate package htop
Refresh APT metadata and retry the install:
sudo apt update
sudo apt install htopThen confirm the system is a supported Debian release and that APT has a normal Debian source enabled:
. /etc/os-release
printf '%s %s\n' "$PRETTY_NAME" "$VERSION_CODENAME"
apt-cache policy htopOn Debian 13, Debian 12, and Debian 11, the candidate should come from a Debian main repository. Containers, minimal images, or custom mirrors can omit normal sources until you restore them.
Source Build Helper Cannot Detect or Build htop
If the manual helper cannot detect the latest release, confirm that GitHub’s API is reachable and that jq can parse the response:
curl -fsSL https://api.github.com/repos/htop-dev/htop/releases/latest | jq -r '.tag_name, (.assets[]?.name)'If that command fails because of a proxy, firewall, DNS issue, or temporary API problem, rerun the helper with a known release tag:
update-htop-source 3.5.1If the configure step reports missing ncurses, capability, sensor, or netlink headers, reinstall the source-build dependencies from the manual method and rerun the helper.
Terminal Display Issues Over SSH
When connecting to a remote Debian server over SSH on Debian, htop may display incorrect colors or line-drawing characters if the local terminal and remote TERM value disagree. Test a common 256-color terminal value for the current session:
export TERM=xterm-256color
htopIf monochrome output is easier to read in a limited terminal, start htop without colors:
htop --no-colorPermission Denied When Killing or Renicing Processes
Regular users cannot freely signal or reprioritize processes owned by root, system services, or other accounts. If htop reports permission errors when you send signals or change nice values, reopen htop with elevated privileges:
sudo htopUse elevated htop only for tasks that need it. For routine monitoring, an unprivileged htop session is safer.
sudo htop Cannot Save Root Configuration
If sudo htop cannot save settings under /root/.config/htop/htoprc, root’s htop configuration directory is missing. Create the directory with root ownership and private permissions, then reopen the elevated htop session:
sudo install -d -m 700 /root/.config/htop
sudo htopUse this fix only for root’s saved htop layout. Normal user settings stay in ~/.config/htop/htoprc and do not need root-owned directories.
Temperature or Sensor Data Is Missing
If htop does not show CPU temperature or sensor meters, install and configure lm-sensors. Not every VM, server, laptop, or kernel exposes useful sensor data, so missing temperature fields are not always an htop problem.
sudo apt install lm-sensors
sudo sensors-detectAccept the safe defaults during detection, restart htop, then press F2 and add a temperature meter if htop detects available sensors.
Conclusion
Htop is installed on Debian through either the recommended APT package or a manually managed GitHub source build. Use htop to inspect live CPU, memory, swap, and process activity, then keep the active method updated with APT or update-htop-source. For remote systems, combine htop with a clean SSH setup and verify the active binary path before switching methods.
Formatting tips for your comment
You can use basic HTML to format your comment. Useful tags currently allowed in published comments:
<code>command</code>command<strong>bold</strong><em>italic</em><blockquote>quote</blockquote>