Linux command: top

1. The Basics

top shows you a list of processes, sorted by CPU use, refreshed every few seconds, with a summary of the whole machine above it. That is the entire idea. Everything worth knowing is in what those numbers actually mean, because several of them mean something quite different from what they look like.

1.1 The Simplest Possible Use

Type the name, nothing else:

$ top

The screen clears and fills with a fixed layout. Press q to quit, or h for help. Those are the only two keys you must know before you start.

top - 17:21:38 up  6:11,  1 user,  load average: 1.63, 1.39, 1.29
Tasks: 517 total,   2 running, 515 sleeping,   0 stopped,   0 zombie
%Cpu(s):  4.7 us,  2.6 sy,  0.0 ni, 92.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :  64026.3 total,  34464.3 free,  14897.2 used,  16868.6 buff/cache
MiB Swap:   8192.0 total,   8192.0 free,      0.0 used.  49129.1 avail Mem

    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
 118289 pe7er     20   0 1448.5g 557844 260284 R  91.7   0.9   1:42.29 chrome
  10681 pe7er     20   0   10.6g   3.7g   1.3g S  16.7   5.9  87:49.77 phpstorm
 106453 pe7er     20   0 1448.4g 251576 157480 S   8.3   0.4  16:10.38 chrome
 120269 pe7er     20   0   14868   5584   3536 R   8.3   0.0   0:00.02 top
      1 root      20   0   24500  15008   9248 S   0.0   0.0   0:04.40 systemd

All the output in this article comes from that machine: sixteen CPU cores, 62.5 GiB of memory, Ubuntu, top from procps-ng 4.0.4.

1.2 The Five Summary Lines

The block at the top describes the machine, not any single process. Each line has its own toggle key, and each one is misread in its own particular way.

1.3 The Task Columns

Below the header comes one row per process. The default columns are these:

The state letters come up constantly in support conversations, so they are worth having straight:

R   running, or ready to run and waiting for a CPU
S   sleeping, waiting for something that can be interrupted
D   uninterruptible sleep, nearly always waiting for disk or network storage
I   idle kernel thread
T   stopped by a job control signal (Ctrl-Z)
t   stopped by a debugger
Z   zombie: finished, but its parent has not collected the exit status

D is the interesting one. A process in D cannot be killed, not even with kill -9, because it is sitting inside a kernel call that has not returned. It is also counted in the load average, which is where most load-average confusion begins.

1.4 The Mental Model

One sentence explains almost every surprise in this article.

top samples. Every field with a percent sign is a difference between two readings, taken over the refresh interval. Every field without one is a total, accumulated since the process started or since boot.

That is why %CPU and TIME+ can disagree so violently. TIME+ says a process has used ninety minutes of CPU since Tuesday. %CPU says it used none in the last three seconds. Both are true, and they answer different questions.

It also explains why the very first screen is not like the ones that follow, and why a script that runs top once gets an answer it should not trust. Section 6.2 measures exactly how bad that is.

3. A Short History

The Linux top is not a descendant of LeFebvre's. It is a re-implementation that borrowed the name, the layout and the three-second beat, and then went its own way. You can read the second half of that story in the copyright file on any Debian or Ubuntu machine:

$ grep -B1 -A1 "James C. Warner" /usr/share/doc/procps/copyright
Files: src/top/*
Copyright: 2002-2022 James C. Warner
License: LGPL-2.0+

Two practical consequences follow, and both catch people out.

First, top is not in POSIX and never has been. There is no standard for it, so there is no guarantee that the flags in your notes work on the next machine. On FreeBSD or macOS you get a descendant of LeFebvre's version, with its own option set and its own field names. Inside a minimal container image you often get BusyBox top, a third implementation again with a different output format entirely. Check what you are actually running before you trust a flag, and read the local manual page rather than one you found online:

$ top -V
top from procps-ng 4.0.4

Second, the options really did keep arriving. -E, -e, -O and the long forms are recent. A five-year-old server may not have them, and a tutorial from 2015 may be describing a program that no longer behaves the same way.

5. Moderate Use Cases

5.1 One Core Pegged, Fifteen Idle

The %Cpu(s) line is an average, and averages hide exactly the problem you are usually hunting. A single-threaded process saturating one core on a sixteen-core machine can only ever raise the average by 6 percent, so the header looks calm while one core is on fire.

Press 1. It splits that one line into one line per core. Here is a machine with a single busy loop running, seen both ways:

# the default, combined view
%Cpu(s): 16.2 us,  0.7 sy,  0.0 ni, 83.0 id,  0.0 wa,  0.0 hi,  0.2 si,  0.0 st

# after pressing 1
%Cpu0  :  3.0 us,  1.0 sy,  0.0 ni, 96.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu1  :  5.1 us,  1.0 sy,  0.0 ni, 93.9 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu2  :  3.0 us,  1.0 sy,  0.0 ni, 96.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu3  : 98.0 us,  0.0 sy,  0.0 ni,  2.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu4  :  3.0 us,  1.0 sy,  0.0 ni, 96.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
...
%Cpu15 :  5.0 us,  1.0 sy,  0.0 ni, 94.1 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st

Sixteen percent in the summary. Ninety-eight percent on core 3. This is the signature of a single-threaded bottleneck, and it is one of the most useful things top can show you: a PHP script, a cron job or a database query that cannot be spread across cores no matter how many you buy.

On a machine with many cores the per-core lines will not all fit. 4 puts several CPUs on each line, and ! combines them in pairs, then fours, then eights. -1 on the command line starts with the toggle already flipped.

5.2 The Cores a Process Is Not Allowed to Use

Section 5.1 showed a process that could only use one core because it had only one thread. There is a second reason a busy process ignores fifteen idle cores, and it is invisible in every column top shows by default: the process may not be allowed on them.

Linux lets you pin a task to a subset of CPUs. taskset reads and sets that mask:

$ taskset -cp 130667                 # -c for a CPU list, -p for an existing pid
pid 130667's current affinity list: 2

$ taskset -c 0,1 ./import.sh         # start something on CPUs 0 and 1 only
$ taskset -cp 0-3 130667             # move a running process onto CPUs 0 to 3

A busy loop pinned to CPU 2 looks completely normal in the task list. It is using an entire core, and top says so:

$ top -b -n 2 -d 1 -p 130667 | tail -1
 130667 pe7er     20   0   10308   3508   3252 R  99.0   0.0   0:12.48 bash

Press 1 and the constraint becomes obvious. One core is flat out and its neighbours are asleep, and no amount of spare capacity elsewhere will help:

%Cpu1  :  1.7 us,  0.0 sy,  0.0 ni, 98.3 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu2  :100.0 us,  0.0 sy,  0.0 ni,  0.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
%Cpu3  :  2.3 us,  0.6 sy,  0.0 ni, 97.2 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
...

That picture is identical to the single-threaded one in section 5.1, which is exactly why it is worth knowing about. The two causes look the same on screen and have completely different fixes: threading the application, or removing the pin. taskset -cp is the one command that tells them apart.

Affinity is rarely set by accident, but it is often set and then forgotten. The usual sources on a server:

top can show you which core a task last ran on. Turn on the P field with f, and watch it stay still for a pinned process and wander for a normal one. The manual adds an honest warning about that column: "the very act of running top may break this weak affinity and cause more processes to change CPUs more often".

One distinction to keep straight, because the two get confused constantly. Affinity says where a task may run. A cgroup CPU quota, the kind a container gets, says how much it may run, without restricting it to particular cores. A process can be throttled to half a CPU while still being scheduled across all sixteen. Section 7.1 covers what top can and cannot see of that.

5.3 A %CPU of 400 Is Not a Bug

By default top runs in what the manual calls Irix mode, where 100 percent means one fully busy core. A process with four busy threads therefore shows 400. This is a compression job with four worker threads:

$ top -b -n 2 -d 1 -p 123850 | tail -1
 123850 pe7er     20   0  372564  70144   2304 S 401.0   0.1   0:16.83 xz

Press H (short for threads-show) and the same process breaks into its threads, each with its own row and its own share:

$ top -b -n 2 -d 1 -H -p 123850 | tail -5
 123852 pe7er     20   0  372564  70144   2304 R  99.9   0.1   0:05.40 xz
 123853 pe7er     20   0  372564  70144   2304 R  99.9   0.1   0:05.39 xz
 123854 pe7er     20   0  372564  70144   2304 R  99.9   0.1   0:05.39 xz
 123855 pe7er     20   0  372564  70144   2304 R  99.9   0.1   0:05.39 xz
 123850 pe7er     20   0  372564  70144   2304 S   1.0   0.1   0:00.05 xz

Four threads at 100 percent and a parent doing the coordination. The 401 was never mysterious; it was four cores plus rounding.

That is the answer you want when a process sits at 100 percent and refuses to go higher: is it one saturated thread, or forty threads doing a little each? Two commands outside top answer it more comfortably, and both show the CPU each thread last ran on:

$ ps -L -p 130929 -o pid,tid,psr,pcpu,comm
 130929  130929   4  0.6 xz            # the parent, idle
 130929  130931   6  102 xz            # tid, psr = which core, pcpu
 130929  130932   3  102 xz
 130929  130933   2  102 xz

$ pidstat -t -p 130929 1 1
Average:  1000  130929       -  300.00  1.00 ...   xz
Average:  1000       -  130931  100.00  0.00 ... |__xz
Average:  1000       -  130932  100.00  0.00 ... |__xz
Average:  1000       -  130933  100.00  0.00 ... |__xz

pidstat -t is the clearer of the two: it prints the process total on one line and indents each thread underneath it. Three threads at 100 and a total of 301 is a healthy parallel job. One thread at 100 and a total of 101, on a process with forty threads, is a bottleneck with a name.

If you prefer the other convention, I switches to Solaris mode, which divides by the number of cores so that 100 percent means the whole machine. The same process, one keystroke apart:

Irix mode Off
 123978 pe7er     20   0  372564  70272   2304 S  25.1   0.1   0:25.04 xz

401 divided by sixteen cores is 25.1. Neither number is wrong; they answer different questions. Irix mode tells you how many cores a process is using, Solaris mode tells you what fraction of the machine it is using. Know which one you are looking at before you quote a figure to somebody, because I is a persistent toggle and a colleague may have flipped it.

5.4 Showing Less

Five hundred rows scrolling past is not diagnosis. top has three separate ways to narrow the list, and they behave differently.

-u (short for filter-only-euser) matches the effective user; -U (short for filter-any-user) matches real, effective, saved or filesystem user. Prefix with ! to invert:

$ top -u www-data           # only the web server's processes
$ top -u mysql              # only the database
$ top -U '!root'            # everything that is not root

-p (short for pid) watches specific processes, up to twenty of them:

$ top -p 1234,5678
$ top -p $(pgrep php-fpm | head -20 | paste -sd,)     # the 20-pid limit, safely

And interactively, o and O build a filter on any field at all. The syntax is a field name, an operator, and a value:

o     then type    COMMAND=chrome       only chrome processes (case ignored)
O     then type    RES>500000           only processes above ~500 MiB resident
o     then type    !USER=root           everything except root
^O                                      show which filters are active
=                                       clear all filters in this window

Now the trap, and it catches everybody once. Filtering the task list does not filter the summary. With a filter showing only chrome, the header still counts the whole machine:

$ top -b -n 1 -u root | sed -n '2p'
Tasks: 515 total,   1 running, 514 sleeping,   0 stopped,   0 zombie

$ top -b -n 1 -u root | tail -n +8 | wc -l
305                              # only 305 root processes are listed

515 in the header, 305 in the list. The one exception is -p, which does restrict the count, so a filtered Tasks: line means you used -p and nothing else. Never quote a summary figure from a filtered screen.

5.5 Seeing What a Process Actually Is

COMMAND shows the program name by default, which is useless when twenty rows all say php-fpm. c (also available as -c, short for cmdline-toggle) swaps it for the full command line:

$ top -b -n 1 -c -w 200 -o +%MEM | sed -n '8p'
  10681 pe7er     20   0   10.6g   3.8g   1.3g S  45.5   6.0  89:33.95 /home/pe7er/.local/share/JetBrains/Toolbox/apps/phpstorm/bin/phpstorm

Kernel threads have no command line, so they appear in square brackets: [kthreadd], [kworker/0:0H]. That is how you tell a kernel thread from a process at a glance, and kernel threads always show 0 for VIRT, RES and SHR.

V turns on forest view, which reorders the list by parentage and draws the tree:

    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    871 root      19  -1   84512  22256  21092 S   0.0   0.0   0:02.22  `- systemd-journal
    987 root      20   0   31520   9372   5148 S   0.0   0.0   0:00.51  `- systemd-udevd
   1743 systemd+  20   0   17564   7528   6760 S   0.0   0.0   0:09.54  `- systemd-oomd
   1749 systemd+  20   0   21872  13264  11088 S   0.0   0.0   0:03.22  `- systemd-resolve
   1977 avahi     20   0   11544   6396   3836 S   0.0   0.0   1:34.01  `- avahi-daemon
   2108 avahi     20   0    8480   1440   1164 S   0.0   0.0   0:00.00      `- avahi-daemon
   1985 root      20   0   13692   6328   6072 S   0.0   0.0   0:00.19  `- bluetoothd

This is how you find out that the mystery process eating CPU was forked by a cron job rather than by the web server. v collapses or expands the children of the top process, and any sort key exits forest view, which is worth remembering before you wonder where your tree went.

5.6 Changing the Columns, and Keeping the Change

f opens the field manager. Arrow keys move, d or space toggles a field on or off, s makes it the sort field, q returns. There are seventy-odd fields available, far more than the dozen shown by default:

$ top -O | tr '\n' ' '
PID PPID UID USER RUID RUSER SUID SUSER GID GROUP PGRP TTY TPGID SID PR NI nTH P
%CPU TIME TIME+ %MEM VIRT SWAP RES CODE DATA SHR nMaj nMin nDRT S COMMAND WCHAN
Flags CGROUPS SUPGIDS SUPGRPS TGID OOMa OOMs ENVIRON vMj vMn USED nsIPC nsMNT
nsNET nsPID nsUSER nsUTS LXC RSan RSfd RSlk RSsh CGNAME NU LOGID EXE RSS PSS
PSan PSfd PSsh USS ioR ioRop ioW ioWop AGID AGNI STARTED ELAPSED %CUU %CUC ...

A handful of these are worth turning on for real work:

Everything you change lasts until you quit, unless you press W. That writes a configuration file and reports where it went:

W

Wrote configuration to '/home/pe7er/.config/procps/toprc'

The legacy location was ~/.toprc, with a leading dot, and it is still honoured. The name actually follows the name of the program, so an alias called t reads and writes procps/trc. The file records the sort field, the visible columns, the colours, the delay and the state of every toggle:

$ head -2 ~/.config/procps/toprc
top's Config File (Linux processes with windows)
Id:k, Mode_altscr=0, Mode_irixps=1, Delay_time=1.0, Curwin=0

Note Delay_time=1.0 there, saved from a session started with -d 1. That single line has consequences well beyond the interactive screen, which is section 6.3.

7. Something Most Users Do Not Know

7.1 Inside a Container, top Reports the Host

This one costs real time and real money, because it makes people size containers by a number that was never about their container.

Here is top running inside a container that has been given a hard limit of 256 MiB of memory and one CPU:

$ docker run --rm -m 256m --cpus 1 mariadb:10.6.18 sh -c 'top -b -n 1 | head -5'
top - 15:28:56 up  6:18,  0 users,  load average: 2.52, 1.67, 1.43
Tasks:   3 total,   1 running,   2 sleeping,   0 stopped,   0 zombie
%Cpu(s): 25.4 us,  3.0 sy,  0.0 ni, 71.6 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :  64026.3 total,  34062.5 free,  12709.0 used,  17254.8 buff/cache
MiB Swap:   8192.0 total,   8192.0 free,      0.0 used.  49266.0 avail Mem

62.5 GiB total. The container may use 256 MiB. And the limit really is in force:

$ docker run --rm -m 256m --cpus 1 mariadb:10.6.18 sh -c \
      'cat /sys/fs/cgroup/memory.max; cat /sys/fs/cgroup/cpu.max; nproc'
268435456                          # 256 MiB, exactly as requested
100000 100000                      # one CPU's worth of quota
16                                 # but the machine still looks like 16 cores

Look at the Tasks: 3 total line, though, because it shows what is going on. The PID namespace is respected, so top sees only the three processes inside the container. The memory and CPU cgroups are not, because top reads /proc/meminfo and /proc/stat, which are the host's files, mounted straight through.

So inside a container, top tells the truth about processes and lies about capacity. The load average is the host's. The CPU percentages are shares of all sixteen host cores. The memory total is the host's RAM, which means %MEM is a fraction of the wrong denominator, and a process at 90 percent of its container limit shows up as 0.4 percent.

When you need the container's own numbers, read the cgroup files or ask the runtime:

$ cat /sys/fs/cgroup/memory.current   /sys/fs/cgroup/memory.max
$ cat /sys/fs/cgroup/cpu.stat
$ docker stats --no-stream          # from the host: real per-container figures

There is a second consequence of that PID namespace, and it bites the moment you try to act on what you saw. A PID only means something inside the namespace you read it in. The same process has one number in the container and a different one on the host:

$ C=$(docker run -d --rm -m 256m mariadb:10.6.18 sleep 120)

# inside the container:
$ docker exec $C ps -eo pid,comm
    PID COMMAND
      1 sleep

# on the host, the very same process:
$ docker inspect -f '{{.State.Pid}}' $C
130140

So a PID copied out of a container's top is meaningless in the host's top, and quite possibly belongs to something else entirely. Worse, a kill 1 that would stop a container's application will, run on the host, be aimed at systemd. Decide which side you are on before you act, and use docker inspect or docker top to translate between the two.

The same warning applies to free, uptime and nproc. It is not a top bug; it is what happens when a program written for whole machines runs inside a slice of one.

7.2 You Cannot Add Up RES

RES is the honest per-process memory number, and the obvious next step is to add the column up and see where the RAM went. That does not work, and the error is large.

$ ps -eo rss= | awk '{s+=$1} END {printf "sum of RES over all processes: %.1f MiB\n", s/1024}'
sum of RES over all processes: 23660.6 MiB

$ top -b -n 1 | sed -n 4p
MiB Mem :  64026.3 total,  33770.9 free,  15078.0 used,  17595.8 buff/cache

23.6 GiB of RES against 15.0 GiB actually in use. The sum is more than half again too big, and on a machine running many copies of the same program the gap is far worse.

The reason is sharing. Shared libraries, the program image itself, copy-on-write pages inherited from a fork, shared memory segments: each page is counted in full against every process that maps it. Twenty PHP-FPM workers forked from one parent each report the parent's memory as their own. The SHR column is telling you roughly how much of RES is at risk of being double counted, which is why SHR sits right next to it.

If you need a number that adds up, ask for the proportional set size, where each shared page is divided by the number of processes sharing it:

PSS    proportional set size: shared pages divided by the number of sharers
USS    unique set size: the pages this process alone holds
RSS    a more precise resident figure, from smaps_rollup

All three are available in top through f, and both the manual and reality agree on the catch: "Accessing smaps values is 10x more costly than other memory statistics", and reading them for another user's processes needs root. Turn them on when you are investigating memory, and turn them off again.

The practical rule: use RES to compare processes with each other, and the summary line to ask how much memory the machine is using. Never use one to derive the other.

7.3 VIRT Means Almost Nothing

The widest number on the screen is the one you should care about least:

    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
 106453 pe7er     20   0 1448.4g 251576 157480 S  16.7   0.4  16:48.36 chrome

1448.4 gibibytes of virtual memory, on a machine with 62.5 GiB of RAM and 8 GiB of swap. That is roughly twenty times more memory than exists anywhere on the box, and nothing is wrong.

VIRT is address space, not memory. It counts everything the process has mapped: code, shared libraries, file mappings, memory that was requested but never touched, and large reservations that runtimes make on principle. Java, Go, Chrome, PostgreSQL and anything using a large mmap arena routinely reserve hundreds of gigabytes of addresses they will never use. Reserving an address costs nothing; only touching a page costs memory, and touched pages appear in RES.

There is one case where VIRT is worth a glance: if it climbs steadily and forever while RES stays flat, something is leaking mappings rather than leaking memory. Otherwise, ignore the column, or press f and remove it so that it stops drawing your eye.

7.4 Where the Numbers Actually Come From

top calculates almost nothing about your machine. It opens files, reads them, subtracts one reading from the previous one, and draws the result. Every number in this article is sitting in a file you can read yourself.

The five summary lines come from three files, read once per refresh:

/proc/loadavg      the load average line
/proc/meminfo      both memory lines
/proc/stat         the %Cpu(s) line and the task state counts
/proc/uptime       the "up 6:11" part of the first line

Every process row comes from two more, read once per process per refresh:

/proc/PID/stat     PID, state, PR, NI, utime, stime, last used CPU  <- most columns
/proc/PID/statm    VIRT, RES, SHR
/proc/PID/cmdline  the COMMAND column, but only when `c' is on
/etc/passwd        turning the numeric UID into the USER column

You do not have to take that on trust. strace will show you every file top opens for a single frame:

$ strace -f -e trace=openat -o tr.txt top -b -n 1 >/dev/null
$ grep -c openat tr.txt
2231

$ grep -oE '"/proc/[0-9]+/[a-z]+"' tr.txt | sed 's|/proc/[0-9]*/|/proc/PID/|' \
      | sort | uniq -c
   1042 "/proc/PID/statm"
   1042 "/proc/PID/stat"

Now do the arithmetic, because it confirms something from section 6.2 by accident. There were 521 processes on the machine at the time. 521 times two is 1042. top -b -n 1 read every process twice, which is the priming sample and the frame, and it is why a single-frame batch run still produces a %CPU column at all. The 0.2 seconds measured in section 6.2 is the gap between those two passes.

Switch on command lines and a third file per process appears, opened exactly as often as the other two. The counts are 1044 rather than 1042 only because a process started between the two runs:

$ strace -f -e trace=openat -o tr2.txt top -b -n 1 -c >/dev/null
   1044 "/proc/PID/statm"
   1044 "/proc/PID/stat"
   1044 "/proc/PID/cmdline"     <- new, and only because of -c

None of those files exists on a disk. They are zero bytes, and the kernel generates the answer at the moment you read it:

$ ls -l /proc/meminfo /proc/stat /proc/1/stat
0 /proc/1/stat
0 /proc/meminfo
0 /proc/stat

Three useful things follow from all of this.

You can skip top entirely. For a script, reading the file is better than parsing a screen: no 0.2 second sample, no configuration file, no 80-column truncation, no failed tty get, and nothing that changes when a colleague presses W.

$ cut -d' ' -f1-3 /proc/loadavg            # the load average, three fields
1.63 1.39 1.29

$ awk '/^MemAvailable/ {print $2/1024 " MiB"}' /proc/meminfo
49164.1 MiB

$ awk '{print $1, $2}' /proc/1234/statm     # VIRT and RES, in pages

Anything reading the same files reports the same numbers. htop, btop, free, uptime, ps and most monitoring agents are all readers of /proc. That is why swapping top for a prettier program changes the presentation and never the meaning, which is section 7.8.

Whose /proc you are reading decides what you are told. Inside a container the process directories belong to the container's PID namespace, while meminfo and stat come straight from the host. That single sentence is the whole of section 7.1.

7.5 top Changes What It Measures

top appears in its own output, and not at the bottom:

 120269 pe7er     20   0   14868   5584   3536 R   8.3   0.0   0:00.02 top

Section 7.4 counted the cost: 2231 file opens for a single frame, two per process plus the summary files. That is not free, and it is measurable:

$ ls /proc | grep -c '^[0-9]'
516                                # processes to walk

$ time top -b -n 1 >/dev/null
real 0m0.23s   user 0m0.00s   sys 0m0.02s

Harmless at the default three seconds. Not harmless at -d 0.1 on a busy production server with thousands of processes, where top can become one of the heavier things running. The manual is candid about the side effects too, noting under the P (last used CPU) field that "the very act of running top may break this weak affinity and cause more processes to change CPUs more often".

Two habits follow. Leave the interval alone unless you have a reason, and if you leave top running in a forgotten SSH session for a week, know that it has woken up 1,200 times an hour, every hour, to walk every process on the machine.

7.6 Hiding the Kernel Threads

On this machine top reports over five hundred tasks, and most of them are not processes in any sense that matters to you. One environment variable removes every kernel thread from both the list and the counts:

$ top -b -n 1 | sed -n 2p
Tasks: 518 total,   1 running, 516 sleeping,   0 stopped,   1 zombie

$ LIBPROC_HIDE_KERNEL=1 top -b -n 1 | sed -n 2p
Tasks: 262 total,   1 running, 260 sleeping,   0 stopped,   1 zombie

518 becomes 262. Half of everything top was showing you was kworker, ksoftirqd, rcu_gp and friends. The value you set does not matter, only that the variable exists, and it works for the whole procps family, so ps obeys it too.

Put it in your shell profile on a server you administer often. It makes top noticeably easier to read, and the kernel threads you actually need to see, a kworker pegged at 100 percent or a stuck jbd2, are exactly the ones you would go looking for deliberately.

7.7 Knowing Where top Stops

top answers one question well: what is happening on this machine right now. Almost every frustration with it comes from asking it something else.

atop deserves the top row. Installed as a service it samples on a timer and writes every sample to a log, so you can go back and look at the ten minutes before the machine fell over. That is the one thing top structurally cannot do, and it is the thing you want most when somebody reports a problem that has already passed. It has to be installed before the incident, which is the whole difficulty with it.

And before adding a tool, check whether top already has a narrower relative that answers your question in one line: uptime for the load average, free -h for the memory summary, pgrep and pidof for finding a PID, w for who is logged in. They all come from the same procps package and read the same files.

7.8 htop and btop, and Why top Is Still Worth Learning

Ask anyone about top and within a sentence you will be told to use htop instead. That advice is mostly right. It is also, on a server you have just been handed, frequently useless, and the reason is one line of package metadata:

$ dpkg-query -W -f='${Package} ${Priority}\n' procps htop btop
btop optional
htop optional
procps required

procps, which ships top, is a required package. It is in every Debian and Ubuntu install, including the minimal ones. htop and btop are optional: someone has to install them, and atop was not installed on this machine at all.

That distinction only matters in the moments when it matters most. A freshly provisioned VPS, a rescue shell, a minimal container image, a customer's server you are looking at for the first time, a box whose outbound network is exactly the thing that is broken. In all of those, top is what you have, and apt install htop is not an option. Learn top because it is always there; use htop when somebody has been kind enough to install it.

When it is there, here is what it genuinely does better:

That last row is a real improvement, and you can see it by running both at the same moment:

top      Tasks: 521 total,   2 running, 519 sleeping,   0 stopped,   0 zombie
htop     Tasks: 265, 2390 thr, 261 kthr; 3 running

One number against three. top says 521 tasks; htop says 265 real processes, 2390 threads between them, and 261 kernel threads counted apart from the rest. The second line is simply more informative.

btop is a different proposition again: graphs over time, mouse support, and a look that needs a modern terminal to render properly. It is pleasant, and it is a viewer rather than a tool you build anything on.

Two things about htop catch people who arrive from top, and both are worth knowing before you type them on a live machine:

$ top  -d 5        # 5 SECONDS between refreshes
$ htop -d 5        # 0.5 seconds. htop counts in TENTHS of a second.

The manual is explicit that htop clamps that value between 1 and 100 tenths, so its slowest refresh is ten seconds and its fastest is a tenth. And the second difference matters if you were hoping to script it:

$ top -n 1 | head -3
top: failed tty get                # refuses cleanly, exit code 1

$ htop -n 1 | head -3
[?1049h[22;0;0t[1;24r(B[m[4l[?7h[H[2J ...
                                   # raw escape codes into your pipe, exit code 0

htop has no batch mode. It has -n to limit the number of frames, but the frames are still full-screen drawing instructions, so a script that captures them gets a screenful of terminal control sequences and no error to tell it so. For anything unattended, that leaves top -b and ps, which is section 9.1's conclusion arriving from a different direction.

Now the part that matters more than any of the above. htop and btop read the same /proc files that top reads. They are nicer windows onto identical numbers, so every misreading in this article survives the switch intact. The container trap from section 7.1 is the clearest proof, with htop installed inside the same 256 MiB container:

$ docker run --rm -t -m 256m --cpus 1 ubuntu:24.04 \
      sh -c 'apt-get install -y htop >/dev/null; cat /sys/fs/cgroup/memory.max; htop'
268435456                          # the container's real limit: 256 MiB

15.1G/62.5G                        # what htop's memory meter shows
Load average: 1.40 1.27 1.29       # and the host's load average

62.5 GiB, the host's RAM, in a container allowed 256 MiB. Exactly what top did, because it is exactly the same file being read. A prettier meter does not make the number mean something different.

So the honest summary is this. htop is the better program to sit in front of, and it is worth installing on every machine you own. It is not a substitute for knowing what the load average counts, what RES double counts, or whose memory you are looking at, and those are the things that actually cost people an afternoon.

9. Common Mistakes

9.1 top Versus ps, and the %CPU That Disagrees

Both programs print a column called %CPU. They mean completely different things, and the difference is not small. This process burned seven seconds of CPU and then went to sleep:

$ top -b -n 1 -p 120358 | tail -1
 120358 pe7er     20   0    8656   2068   2068 S   0.0   0.0   0:07.04 sleep

$ ps -o pid,%cpu,time,etime,comm -p 120358
    PID %CPU     TIME     ELAPSED COMMAND
 120358 67.4 00:00:07       00:10 sleep

# and it is not the first-frame problem from section 6.2 either,
# the second frame agrees:
$ top -b -n 2 -d 1 -p 120358 | tail -1
 120358 pe7er     20   0    8656   2068   2068 S   0.0   0.0   0:07.04 sleep

Zero, and 67.4, for the same process at the same moment. Neither is wrong:

• top reports CPU used since the last refresh. The process is asleep now, so 0.0 is correct.
• ps reports total CPU divided by total lifetime. Seven seconds of CPU in ten seconds of life is 67.4 percent, averaged over its whole existence.

That is why ps aux can show a web server process at 40 percent that is doing nothing at all: it was busy at start-up an hour ago and the average never recovers. If you want the ps figure inside top, the %CUU field is exactly that, and having both columns side by side answers "is this process busy now, or has it always been busy?" in one glance.

The clean split: top is for looking, ps is for scripting. When a script needs a process list, ps -eo pid,pcpu,rss,comm --sort=-pcpu is shorter, faster, stable and free of every trap in section 6.

9.2 Myth Versus Reality

9.3 Other Traps to Avoid

• Pressing k and then Enter. The PID defaults to the first row, which is the busiest process on the machine. That is rarely the one you meant to kill.
• Leaving -d 0.1 running on a production server. Every refresh reads several files for every process. At 0.1 seconds on a machine with thousands of processes, top becomes part of the load it is reporting.
• Parsing top output by column number. The columns depend on the rcfile, the H and c toggles and the terminal width. Use ps -o with named fields instead.
• Trusting %MEM inside a container. The denominator is the host's RAM, so a process at its container limit can read 0.4 percent.
• Chasing a kworker thread. A busy kworker is the kernel doing work for something. Find the process causing it rather than trying to renice a kernel thread.
• Reading %CPU immediately after starting top. The first screen is the unreliable one. Wait for the second refresh before believing anything.
• Assuming Tasks: 517 total means 517 programs. Half are kernel threads (section 7.6), and with H on, the count switches to threads and jumps again.
• Killing a zombie. A Z process is already dead and holds no memory. It is waiting for its parent to collect the exit status, so the process to look at is the parent.
• Sorting by %CPU while searching with L. The manual warns about this directly: rows move between refreshes, so a search on an unstable sort column keeps losing its place. Sort by PID while you search.
• Calling it from a script without -b. top takes over the terminal, so a cron job or a CI step that forgets batch mode produces failed tty get and exit code 1, and nothing else.
• Reporting swap used as a problem. Pages moved out while idle are the kernel doing its job. Swap that is actively churning is the problem, and vmstat 1 shows it in the si and so columns.