1HTOP(1) User Commands HTOP(1)
2
6 pcp-htop - interactive process viewer
7
9 htop [-dCFhpustvH]
10 pcp htop [-dCFhpustvH] [--host/-h host]
11
13 htop is a cross-platform ncurses-based process viewer.
14 It is similar to top, but allows you to scroll vertically and horizon‐
16 tally, and interact using a pointing device (mouse). You can observe
17 all processes running on the system, along with their command line ar‐
18 guments, as well as view them in a tree format, select multiple pro‐
19 cesses and act on them all at once.
20 Tasks related to processes (killing, renicing) can be done without en‐
22 tering their PIDs.
23 pcp-htop is a version of htop built using the Performance Co-Pilot
25 (PCP) Metrics API (see PCPIntro(1), PMAPI(3)), allowing to extend htop
26 to display values from arbitrary metrics. See the section below titled
27 CONFIG FILES for further details.
28
30 Mandatory arguments to long options are mandatory for short options
31 too.
32 -d --delay=DELAY
34 Delay between updates, in tenths of a second. If the delay value
35 is less than 1, it is increased to 1, i.e. 1/10 second. If the
36 delay value is greater than 100, it is decreased to 100, i.e. 10
37 seconds.
38 -C --no-color --no-colour
40 Start htop in monochrome mode
41 -F --filter=FILTER
43 Filter processes by command
44 -h --help
46 Display a help message and exit
47 -p --pid=PID,PID...
49 Show only the given PIDs
50 -s --sort-key COLUMN
52 Sort by this column (use --sort-key help for a column list).
53 This will force a list view unless you specify -t at the same
54 time.
55 -u --user=USERNAME
57 Show only the processes of a given user
58 -U --no-unicode
60 Do not use unicode but ASCII characters for graph meters
61 -M --no-mouse
63 Disable support of mouse control
64 --readonly
66 Disable all system and process changing features
67 -V --version
69 Output version information and exit
70 -t --tree
72 Show processes in tree view. This can be used to force a tree
73 view when requesting a sort order with -s.
74 -H --highlight-changes=DELAY
76 Highlight new and old processes
77 --drop-capabilities[=off|basic|strict]
79 Linux only; requires libcap support.
80 Drop unneeded Linux capabilities. In strict mode features like
81 killing, changing process priorities, and reading process delay
82 accounting information will not work, due to less capabilities
83 held.
84
86 The following commands are supported while in htop:
87 Up, Alt-k
89 Select (highlight) the previous process in the process list.
90 Scroll the list if necessary.
91 Down, Alt-j
93 Select (highlight) the next process in the process list. Scroll
94 the list if necessary.
95 Left, Alt-h
97 Scroll the process list left.
98 Right, Alt-l
100 Scroll the process list right.
101 PgUp, PgDn
103 Scroll the process list up or down one window.
104 Home Scroll to the top of the process list and select the first
106 process.
107 End Scroll to the bottom of the process list and select the last
109 process.
110 Ctrl-A, ^
112 Scroll left to the beginning of the process entry (i.e. beginning
113 of line).
114 Ctrl-E, $
116 Scroll right to the end of the process entry (i.e. end of line).
117 Space
119 Tag or untag a process. Commands that can operate on multiple pro‐
120 cesses, like "kill", will then apply over the list of tagged pro‐
121 cesses, instead of the currently highlighted one.
122 c Tag the current process and its children. Commands that can oper‐
124 ate on multiple processes, like "kill", will then apply over the
125 list of tagged processes, instead of the currently highlighted
126 one.
127 U Untag all processes (remove all tags added with the Space or c
129 keys).
130 s Trace process system calls: if strace(1) is installed, pressing
132 this key will attach it to the currently selected process, pre‐
133 senting a live update of system calls issued by the process.
134 l Display open files for a process: if lsof(1) is installed, press‐
136 ing this key will display the list of file descriptors opened by
137 the process.
138 w Display the command line of the selected process in a separate
140 screen, wrapped onto multiple lines as needed.
141 x Display the active file locks of the selected process in a sepa‐
143 rate screen.
144 F1, h, ?
146 Go to the help screen
147 F2, S
149 Go to the setup screen, where you can configure the meters dis‐
150 played at the top of the screen, set various display options,
151 choose among color schemes, and select which columns are dis‐
152 played, in which order.
153 F3, /
155 Incrementally search the command lines of all the displayed pro‐
156 cesses. The currently selected (highlighted) command will update
157 as you type. While in search mode, pressing F3 will cycle through
158 matching occurrences. Pressing Shift-F3 will cycle backwards.
159 Alternatively the search can be started by simply typing the com‐
161 mand you are looking for, although for the first character normal
162 key bindings take precedence.
163 F4, \
165 Incremental process filtering: type in part of a process command
166 line and only processes whose names match will be shown. To cancel
167 filtering, enter the Filter option again and press Esc.
168 F5, t
170 Tree view: organize processes by parenthood, and layout the rela‐
171 tions between them as a tree. Toggling the key will switch between
172 tree and your previously selected sort view. Selecting a sort view
173 will exit tree view.
174 F6, <, >
176 Selects a field for sorting, also accessible through < and >. The
177 current sort field is indicated by a highlight in the header.
178 F7, ]
180 Increase the selected process's priority (subtract from 'nice'
181 value). This can only be done by the superuser.
182 F8, [
184 Decrease the selected process's priority (add to 'nice' value)
185 Shift-F7, }
187 Increase the selected process's autogroup priority (subtract from
188 autogroup 'nice' value). This can only be done by the superuser.
189 Shift-F8, {
191 Decrease the selected process's autogroup priority (add to auto‐
192 group 'nice' value)
193 F9, k
195 "Kill" process: sends a signal which is selected in a menu, to one
196 or a group of processes. If processes were tagged, sends the sig‐
197 nal to all tagged processes. If none is tagged, sends to the cur‐
198 rently selected process.
199 F10, q
201 Quit
202 I Invert the sort order: if sort order is increasing, switch to de‐
204 creasing, and vice-versa.
205 +, -, *
207 When in tree view mode, expand or collapse subtree. When a subtree
208 is collapsed a "+" sign shows to the left of the process name.
209 Pressing "*" will expand or collapse all children of PIDs without
210 parents, so typically PID 1 (init) and PID 2 (kthreadd on Linux,
211 if kernel threads are shown).
212 a (on multiprocessor machines)
214 Set CPU affinity: mark which CPUs a process is allowed to use.
215 u Show only processes owned by a specified user.
217 N Sort by PID.
219 M Sort by memory usage (top compatibility key).
221 P Sort by processor usage (top compatibility key).
223 T Sort by time (top compatibility key).
225 F "Follow" process: if the sort order causes the currently selected
227 process to move in the list, make the selection bar follow it.
228 This is useful for monitoring a process: this way, you can keep a
229 process always visible on screen. When a movement key is used,
230 "follow" loses effect.
231 K Hide kernel threads: prevent the threads belonging the kernel to
233 be displayed in the process list. (This is a toggle key.)
234 H Hide user threads: on systems that represent them differently than
236 ordinary processes (such as recent NPTL-based systems), this can
237 hide threads from userspace processes in the process list. (This
238 is a toggle key.)
239 p Show full paths to running programs, where applicable. (This is a
241 toggle key.)
242 Z Pause/resume process updates.
244 m Merge exe, comm and cmdline, where applicable. (This is a toggle
246 key.)
247 Ctrl-L
249 Refresh: redraw screen and recalculate values.
250 Numbers
252 PID search: type in process ID and the selection highlight will be
253 moved to it.
254
256 The following columns can display data about each process. A value of
257 '-' in all the rows indicates that a column is unsupported on your sys‐
258 tem, or currently unimplemented in htop. The names below are the ones
259 used in the "Available Columns" section of the setup screen. If a dif‐
260 ferent name is shown in htop's main screen, it is shown below in paren‐
261 thesis.
262 Command
264 The full command line of the process (i.e. program name and argu‐
265 ments).
266 If the option 'Merge exe, comm and cmdline in Command' (toggled by
268 the 'm' key) is active, the executable path (/proc/[pid]/exe) and
269 the command name (/proc/[pid]/comm) are also shown merged with the
270 command line, if available.
271 The program basename is highlighted if set in the configuration.
273 Additional highlighting can be configured for stale executables
274 (cf. Exe column below).
275 Comm The command name of the process obtained from /proc/[pid]/comm, if
277 readable.
278 Exe The abbreviated basename of the executable of the process, ob‐
280 tained from /proc/[pid]/exe, if readable. htop is able to read
281 this file on linux for ALL the processes only if it has the capa‐
282 bility CAP_SYS_PTRACE or root privileges.
283 The basename is marked in red if the executable used to run the
285 process has been replaced or deleted on disk since the process
286 started. This additional markup can be configured.
287 PID The process ID.
289 STATE (S)
291 The state of the process:
292 S for sleeping (idle)
293 R for running
294 D for disk sleep (uninterruptible)
295 Z for zombie (waiting for parent to read its exit status)
296 T for traced or suspended (e.g by SIGTSTP)
297 W for paging
298 PPID The parent process ID.
300 PGRP The process's group ID.
302 SESSION (SID)
304 The process's session ID.
305 TTY The controlling terminal of the process.
307 TPGID
309 The process ID of the foreground process group of the controlling
310 terminal.
311 MINFLT
313 The number of page faults happening in the main memory.
314 CMINFLT
316 The number of minor faults for the process's waited-for children
317 (see MINFLT above).
318 MAJFLT
320 The number of page faults happening out of the main memory.
321 CMAJFLT
323 The number of major faults for the process's waited-for children
324 (see MAJFLT above).
325 UTIME (UTIME+)
327 The user CPU time, which is the amount of time the process has
328 spent executing on the CPU in user mode (i.e. everything but sys‐
329 tem calls), measured in clock ticks.
330 STIME (STIME+)
332 The system CPU time, which is the amount of time the kernel has
333 spent executing system calls on behalf of the process, measured in
334 clock ticks.
335 CUTIME (CUTIME+)
337 The children's user CPU time, which is the amount of time the
338 process's waited-for children have spent executing in user mode
339 (see UTIME above).
340 CSTIME (CSTIME+)
342 The children's system CPU time, which is the amount of time the
343 kernel has spent executing system calls on behalf of all the
344 process's waited-for children (see STIME above).
345 PRIORITY (PRI)
347 The kernel's internal priority for the process, usually just its
348 nice value plus twenty. Different for real-time processes.
349 NICE (NI)
351 The nice value of a process, from 19 (low priority) to -20 (high
352 priority). A high value means the process is being nice, letting
353 others have a higher relative priority. The usual OS permission
354 restrictions for adjusting priority apply.
355 STARTTIME (START)
357 The time the process was started.
358 PROCESSOR (CPU)
360 The ID of the CPU the process last executed on.
361 M_VIRT (VIRT)
363 The size of the virtual memory of the process.
364 M_RESIDENT (RES)
366 The resident set size (text + data + stack) of the process (i.e.
367 the size of the process's used physical memory).
368 M_SHARE (SHR)
370 The size of the process's shared pages.
371 M_TRS (CODE)
373 The text resident set size of the process (i.e. the size of the
374 process's executable instructions).
375 M_DRS (DATA)
377 The data resident set size (data + stack) of the process (i.e. the
378 size of anything except the process's executable instructions).
379 M_LRS (LIB)
381 The library size of the process.
382 M_SWAP (SWAP)
384 The size of the process's swapped pages.
385 M_PSS (PSS)
387 The proportional set size, same as M_RESIDENT but each page is di‐
388 vided by the number of processes sharing it.
389 M_M_PSSWP (PSSWP)
391 The proportional swap share of this mapping, unlike M_SWAP this
392 does not take into account swapped out page of underlying shmem
393 objects.
394 ST_UID (UID)
396 The user ID of the process owner.
397 PERCENT_CPU (CPU%)
399 The percentage of the CPU time that the process is currently us‐
400 ing. This is the default way to represent CPU usage in Linux.
401 Each process can consume up to 100% which means the full capacity
402 of the core it is running on. This is sometimes called "Irix mode"
403 e.g. in top(1).
404 PERCENT_NORM_CPU (NCPU%)
406 The percentage of the CPU time that the process is currently using
407 normalized by CPU count. This is sometimes called "Solaris mode"
408 e.g. in top(1).
409 PERCENT_MEM (MEM%)
411 The percentage of memory the process is currently using (based on
412 the process's resident memory size, see M_RESIDENT above).
413 USER The username of the process owner, or the user ID if the name
415 can't be determined.
416 TIME (TIME+)
418 The time, measured in clock ticks that the process has spent in
419 user and system time (see UTIME, STIME above).
420 NLWP The number of Light-Weight Processes (=threads) in the process.
422 TGID The thread group ID.
424 CTID OpenVZ container ID, a.k.a virtual environment ID.
426 VPID OpenVZ process ID.
428 VXID VServer process ID.
430 RCHAR (RD_CHAR)
432 The number of bytes the process has read.
433 WCHAR (WR_CHAR)
435 The number of bytes the process has written.
436 SYSCR (RD_SYSC)
438 The number of read(2) syscalls for the process.
439 SYSCW (WR_SYSC)
441 The number of write(2) syscalls for the process.
442 RBYTES (IO_RBYTES)
444 Bytes of read(2) I/O for the process.
445 WBYTES (IO_WBYTES)
447 Bytes of write(2) I/O for the process.
448 CNCLWB (IO_CANCEL)
450 Bytes of cancelled write(2) I/O.
451 IO_READ_RATE (DISK READ)
453 The I/O rate of read(2) in bytes per second, for the process.
454 IO_WRITE_RATE (DISK WRITE)
456 The I/O rate of write(2) in bytes per second, for the process.
457 IO_RATE (DISK R/W)
459 The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
460 CGROUP
462 Which cgroup the process is in.
463 OOM OOM killer score.
465 CTXT Incremental sum of voluntary and nonvoluntary context switches.
467 IO_PRIORITY (IO)
469 The I/O scheduling class followed by the priority if the class
470 supports it:
471 R for Realtime
472 B for Best-effort
473 id for Idle
474 PERCENT_CPU_DELAY (CPUD%)
476 The percentage of time spent waiting for a CPU (while runnable).
477 Requires CAP_NET_ADMIN.
478 PERCENT_IO_DELAY (IOD%)
480 The percentage of time spent waiting for the completion of syn‐
481 chronous block I/O. Requires CAP_NET_ADMIN.
482 PERCENT_SWAP_DELAY (SWAPD%)
484 The percentage of time spent swapping in pages. Requires
485 CAP_NET_ADMIN.
486 COMM The command name for the process. Requires Linux kernel 2.6.33 or
488 newer.
489 EXE The executable file of the process as reported by the kernel. Re‐
491 quires CAP_SYS_PTRACE and PTRACE_MODE_READ_FSCRED.
492 AGRP The autogroup identifier for the process. Requires Linux CFS to be
494 enabled.
495 ANI The autogroup nice value for the process autogroup. Requires Linux
497 CFS to be enabled.
498 All other flags
500 Currently unsupported (always displays '-').
501
503 While htop depends on most of the libraries it uses at build time there
504 are two noteworthy exceptions to this rule. These exceptions both re‐
505 late to data displayed in meters displayed in the header of htop and
506 were intentionally created as optional runtime dependencies instead.
507 These exceptions are described below:
508 libsystemd
510 The bindings for libsystemd are used in the SystemD meter to de‐
511 termine the number of active services and the overall system
512 state. Looking for the functions to determine these information
513 at runtime allows for builds to support these meters without
514 forcing the package manager to install these libraries on sys‐
515 tems that otherwise don't use systemd.
516 Summary: no build time dependency, optional runtime dependency
518 on libsystemd via dynamic loading, with systemctl(1) fallback.
519 libsensors
521 The bindings for libsensors are used for the CPU temperature
522 readings in the CPU usage meters if displaying the temperature
523 is enabled through the setup screen. In order for htop to show
524 these temperatures correctly though, a proper configuration of
525 libsensors through its usual configuration files is assumed and
526 that all CPU cores correspond to temperature sensors from the
527 coretemp driver with core 0 corresponding to a sensor labelled
528 "Core 0". The package temperature may be given as "Package id
529 0". If missing it is inferred as the maximum value from the
530 available per-core readings.
531 Summary: build time dependency on libsensors(3) C header files,
533 optional runtime dependency on libsensors(3) via dynamic load‐
534 ing.
535
537 By default htop reads its configuration from the XDG-compliant path
538 ~/.config/htop/htoprc. The configuration file is overwritten by htop's
539 in-program Setup configuration, so it should not be hand-edited. If no
540 user configuration exists htop tries to read the system-wide configura‐
541 tion from /etc/pcp/htoprc and as a last resort, falls back to its hard
542 coded defaults.
543 You may override the location of the configuration file using the $HTO‐
545 PRC environment variable (so you can have multiple configurations for
546 different machines that share the same home directory, for example).
547 The pcp-htop utility makes use of htoprc in exactly the same way. In
549 addition, it supports additional configuration files allowing new me‐
550 ters and columns to be added to the display via the usual Setup func‐
551 tion, which will display additional Available Meters and Available Col‐
552 umn entries for each runtime configured meter or column.
553 These pcp-htop configuration files are read once at startup. The for‐
555 mat of these files is described in detail in the pcp-htop(5) manual
556 page.
557 This functionality makes available many thousands of Performance Co-Pi‐
559 lot metrics for display by pcp-htop, as well as the ability to display
560 custom metrics added at individual sites. Applications and services
561 instrumented using the OpenMetrics format https://openmetrics.io can
562 also be displayed by pcp-htop if the pmdaopenmetrics(1) component is
563 configured.
564
566 Memory sizes in htop are displayed in a human-readable form. Sizes are
567 printed in powers of 1024. (e.g., 1023M = 1072693248 Bytes)
568 The decision to use this convention was made in order to conserve
570 screen space and make memory size representations consistent throughout
571 htop.
572
574 proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
575
577 pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
578
580 htop was originally developed by Hisham Muhammad. Nowadays it is main‐
581 tained by the community at <htop@groups.io>.
582 pcp-htop is maintained as a collaboration between the <htop@groups.io>
584 and <pcp@groups.io> communities, and forms part of the Performance Co-
585 Pilot suite of tools.
586
588 Copyright © 2004-2019 Hisham Muhammad.
589 Copyright © 2020-2021 htop dev team.
590 License GPLv2+: GNU General Public License version 2 or, at your op‐
592 tion, any later version.
593 This is free software: you are free to change and redistribute it.
595 There is NO WARRANTY, to the extent permitted by law.
596Performance Co-Pilot 2021 HTOP(1)