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 terms matching the commands. The terms are
44 matched case-insensitive and as fixed strings (not regexs). You
45 can separate multiple terms with "|".
46 -h --help
48 Display a help message and exit
49 -p --pid=PID,PID...
51 Show only the given PIDs
52 -s --sort-key COLUMN
54 Sort by this column (use --sort-key help for a column list).
55 This will force a list view unless you specify -t at the same
56 time.
57 -u --user=USERNAME|UID
59 Show only the processes of a given user
60 -U --no-unicode
62 Do not use unicode but ASCII characters for graph meters
63 -M --no-mouse
65 Disable support of mouse control
66 --readonly
68 Disable all system and process changing features
69 -V --version
71 Output version information and exit
72 -t --tree
74 Show processes in tree view. This can be used to force a tree
75 view when requesting a sort order with -s.
76 -H --highlight-changes=DELAY
78 Highlight new and old processes
79 --drop-capabilities[=off|basic|strict]
81 Linux only; requires libcap support.
82 Drop unneeded Linux capabilities. In strict mode features like
83 killing, changing process priorities, and reading process delay
84 accounting information will not work, due to less capabilities
85 held.
86
88 The following commands are supported while in htop:
89 Tab, Shift-Tab
91 Select the next / the previous screen tab to display. You can en‐
92 able showing the screen tab names in the Setup screen (F2).
93 Up, Alt-k
95 Select (highlight) the previous process in the process list.
96 Scroll the list if necessary.
97 Down, Alt-j
99 Select (highlight) the next process in the process list. Scroll
100 the list if necessary.
101 Left, Alt-h
103 Scroll the process list left.
104 Right, Alt-l
106 Scroll the process list right.
107 PgUp, PgDn
109 Scroll the process list up or down one window.
110 Home Scroll to the top of the process list and select the first
112 process.
113 End Scroll to the bottom of the process list and select the last
115 process.
116 Ctrl-A, ^
118 Scroll left to the beginning of the process entry (i.e. beginning
119 of line).
120 Ctrl-E, $
122 Scroll right to the end of the process entry (i.e. end of line).
123 Space
125 Tag or untag a process. Commands that can operate on multiple pro‐
126 cesses, like "kill", will then apply over the list of tagged pro‐
127 cesses, instead of the currently highlighted one.
128 c Tag the current process and its children. Commands that can oper‐
130 ate on multiple processes, like "kill", will then apply over the
131 list of tagged processes, instead of the currently highlighted
132 one.
133 U Untag all processes (remove all tags added with the Space or c
135 keys).
136 s Trace process system calls: if strace(1) is installed, pressing
138 this key will attach it to the currently selected process, pre‐
139 senting a live update of system calls issued by the process.
140 l Display open files for a process: if lsof(1) is installed, press‐
142 ing this key will display the list of file descriptors opened by
143 the process.
144 w Display the command line of the selected process in a separate
146 screen, wrapped onto multiple lines as needed.
147 x Display the active file locks of the selected process in a sepa‐
149 rate screen.
150 F1, h, ?
152 Go to the help screen
153 F2, S
155 Go to the setup screen, where you can configure the meters dis‐
156 played at the top of the screen, set various display options,
157 choose among color schemes, and select which columns are dis‐
158 played, in which order.
159 F3, /
161 Incrementally search the command lines of all the displayed pro‐
162 cesses. The currently selected (highlighted) command will update
163 as you type. While in search mode, pressing F3 will cycle through
164 matching occurrences. Pressing Shift-F3 will cycle backwards.
165 Alternatively the search can be started by simply typing the com‐
167 mand you are looking for, although for the first character normal
168 key bindings take precedence.
169 F4, \
171 Incremental process filtering: type in part of a process command
172 line and only processes whose names match will be shown. To cancel
173 filtering, enter the Filter option again and press Esc. The
174 matching is done case-insensitive. Terms are fixed strings (no
175 regex). You can separate multiple terms with "|".
176 F5, t
178 Tree view: organize processes by parenthood, and layout the rela‐
179 tions between them as a tree. Toggling the key will switch between
180 tree and your previously selected sort view. Selecting a sort view
181 will exit tree view.
182 F6, <, >
184 Selects a field for sorting, also accessible through < and >. The
185 current sort field is indicated by a highlight in the header.
186 F7, ]
188 Increase the selected process's priority (subtract from 'nice'
189 value). This can only be done by the superuser.
190 F8, [
192 Decrease the selected process's priority (add to 'nice' value)
193 Shift-F7, }
195 Increase the selected process's autogroup priority (subtract from
196 autogroup 'nice' value). This can only be done by the superuser.
197 Shift-F8, {
199 Decrease the selected process's autogroup priority (add to auto‐
200 group 'nice' value)
201 F9, k
203 "Kill" process: sends a signal which is selected in a menu, to one
204 or a group of processes. If processes were tagged, sends the sig‐
205 nal to all tagged processes. If none is tagged, sends to the cur‐
206 rently selected process.
207 F10, q
209 Quit
210 I Invert the sort order: if sort order is increasing, switch to de‐
212 creasing, and vice-versa.
213 +, -, *
215 When in tree view mode, expand or collapse subtree. When a subtree
216 is collapsed a "+" sign shows to the left of the process name.
217 Pressing "*" will expand or collapse all children of PIDs without
218 parents, so typically PID 1 (init) and PID 2 (kthreadd on Linux,
219 if kernel threads are shown).
220 a (on multiprocessor machines)
222 Set CPU affinity: mark which CPUs a process is allowed to use.
223 u Show only processes owned by a specified user.
225 N Sort by PID.
227 M Sort by memory usage (top compatibility key).
229 P Sort by processor usage (top compatibility key).
231 T Sort by time (top compatibility key).
233 F "Follow" process: if the sort order causes the currently selected
235 process to move in the list, make the selection bar follow it.
236 This is useful for monitoring a process: this way, you can keep a
237 process always visible on screen. When a movement key is used,
238 "follow" loses effect.
239 K Hide kernel threads: prevent the threads belonging the kernel to
241 be displayed in the process list. (This is a toggle key.)
242 H Hide user threads: on systems that represent them differently than
244 ordinary processes (such as recent NPTL-based systems), this can
245 hide threads from userspace processes in the process list. (This
246 is a toggle key.)
247 p Show full paths to running programs, where applicable. (This is a
249 toggle key.)
250 Z Pause/resume process updates.
252 m Merge exe, comm and cmdline, where applicable. (This is a toggle
254 key.)
255 Ctrl-L
257 Refresh: redraw screen and recalculate values.
258 Numbers
260 PID search: type in process ID and the selection highlight will be
261 moved to it.
262
264 The following columns can display data about each process. A value of
265 '-' in all the rows indicates that a column is unsupported on your sys‐
266 tem, or currently unimplemented in htop. The names below are the ones
267 used in the "Available Columns" section of the setup screen. If a dif‐
268 ferent name is shown in htop's main screen, it is shown below in paren‐
269 thesis.
270 Command
272 The full command line of the process (i.e. program name and argu‐
273 ments).
274 If the option 'Merge exe, comm and cmdline in Command' (toggled by
276 the 'm' key) is active, the executable path (/proc/[pid]/exe) and
277 the command name (/proc/[pid]/comm) are also shown merged with the
278 command line, if available.
279 The program basename is highlighted if set in the configuration.
281 Additional highlighting can be configured for stale executables
282 (cf. EXE column below).
283 COMM The command name of the process obtained from /proc/[pid]/comm, if
285 readable.
286 Requires Linux kernel 2.6.33 or newer.
288 EXE The abbreviated basename of the executable of the process, ob‐
290 tained from /proc/[pid]/exe, if readable. htop is able to read
291 this file on linux for ALL the processes only if it has the capa‐
292 bility CAP_SYS_PTRACE or root privileges.
293 The basename is marked in red if the executable used to run the
295 process has been replaced or deleted on disk since the process
296 started. The information is obtained by processing the contents of
297 /proc/[pid]/exe.
298 Furthermore the basename is marked in yellow if any library is re‐
300 ported as having been replaced or deleted on disk since it was
301 last loaded. The information is obtained by processing the con‐
302 tents of /proc/[pid]/maps.
303 When deciding the color the replacement of the main executable al‐
305 ways takes precedence over replacement of any other library. If
306 only the memory map indicates a replacement of the main exe‐
307 cutable, this will show as if any other library had been replaced
308 or deleted.
309 This additional color markup can be configured in the "Display Op‐
311 tions" section of the setup screen.
312 Displaying EXE requires CAP_SYS_PTRACE and PTRACE_MODE_READ_FS‐
314 CRED.
315 PID The process ID.
317 STATE (S)
319 The state of the process:
320 S for sleeping (idle)
321 R for running
322 D for disk sleep (uninterruptible)
323 Z for zombie (waiting for parent to read its exit status)
324 T for traced or suspended (e.g by SIGTSTP)
325 W for paging
326 PPID The parent process ID.
328 PGRP The process's group ID.
330 SESSION (SID)
332 The process's session ID.
333 TTY The controlling terminal of the process.
335 TPGID
337 The process ID of the foreground process group of the controlling
338 terminal.
339 MINFLT
341 The number of page faults happening in the main memory.
342 CMINFLT
344 The number of minor faults for the process's waited-for children
345 (see MINFLT above).
346 MAJFLT
348 The number of page faults happening out of the main memory.
349 CMAJFLT
351 The number of major faults for the process's waited-for children
352 (see MAJFLT above).
353 UTIME (UTIME+)
355 The user CPU time, which is the amount of time the process has
356 spent executing on the CPU in user mode (i.e. everything but sys‐
357 tem calls), measured in clock ticks.
358 STIME (STIME+)
360 The system CPU time, which is the amount of time the kernel has
361 spent executing system calls on behalf of the process, measured in
362 clock ticks.
363 CUTIME (CUTIME+)
365 The children's user CPU time, which is the amount of time the
366 process's waited-for children have spent executing in user mode
367 (see UTIME above).
368 CSTIME (CSTIME+)
370 The children's system CPU time, which is the amount of time the
371 kernel has spent executing system calls on behalf of all the
372 process's waited-for children (see STIME above).
373 PRIORITY (PRI)
375 The kernel's internal priority for the process, usually just its
376 nice value plus twenty. Different for real-time processes.
377 NICE (NI)
379 The nice value of a process, from 19 (low priority) to -20 (high
380 priority). A high value means the process is being nice, letting
381 others have a higher relative priority. The usual OS permission
382 restrictions for adjusting priority apply.
383 STARTTIME (START)
385 The time the process was started.
386 PROCESSOR (CPU)
388 The ID of the CPU the process last executed on.
389 M_VIRT (VIRT)
391 The size of the virtual memory of the process.
392 M_RESIDENT (RES)
394 The resident set size (text + data + stack) of the process (i.e.
395 the size of the process's used physical memory).
396 M_SHARE (SHR)
398 The size of the process's shared pages.
399 M_TRS (CODE)
401 The text resident set size of the process (i.e. the size of the
402 process's executable instructions).
403 M_DRS (DATA)
405 The data resident set size (data + stack) of the process (i.e. the
406 size of anything except the process's executable instructions).
407 M_LRS (LIB)
409 The library size of the process.
410 M_SWAP (SWAP)
412 The size of the process's swapped pages.
413 M_PSS (PSS)
415 The proportional set size, same as M_RESIDENT but each page is di‐
416 vided by the number of processes sharing it.
417 M_M_PSSWP (PSSWP)
419 The proportional swap share of this mapping, unlike M_SWAP this
420 does not take into account swapped out page of underlying shmem
421 objects.
422 ST_UID (UID)
424 The user ID of the process owner.
425 PERCENT_CPU (CPU%)
427 The percentage of the CPU time that the process is currently us‐
428 ing. This is the default way to represent CPU usage in Linux.
429 Each process can consume up to 100% which means the full capacity
430 of the core it is running on. This is sometimes called "Irix mode"
431 e.g. in top(1).
432 PERCENT_NORM_CPU (NCPU%)
434 The percentage of the CPU time that the process is currently using
435 normalized by CPU count. This is sometimes called "Solaris mode"
436 e.g. in top(1).
437 PERCENT_MEM (MEM%)
439 The percentage of memory the process is currently using (based on
440 the process's resident memory size, see M_RESIDENT above).
441 USER The username of the process owner, or the user ID if the name
443 can't be determined.
444 TIME (TIME+)
446 The time, measured in clock ticks that the process has spent in
447 user and system time (see UTIME, STIME above).
448 NLWP The number of Light-Weight Processes (=threads) in the process.
450 TGID The thread group ID.
452 CTID OpenVZ container ID, a.k.a virtual environment ID.
454 VPID OpenVZ process ID.
456 VXID VServer process ID.
458 RCHAR (RD_CHAR)
460 The number of bytes the process has read.
461 WCHAR (WR_CHAR)
463 The number of bytes the process has written.
464 SYSCR (RD_SYSC)
466 The number of read(2) syscalls for the process.
467 SYSCW (WR_SYSC)
469 The number of write(2) syscalls for the process.
470 RBYTES (IO_RBYTES)
472 Bytes of read(2) I/O for the process.
473 WBYTES (IO_WBYTES)
475 Bytes of write(2) I/O for the process.
476 CNCLWB (IO_CANCEL)
478 Bytes of cancelled write(2) I/O.
479 IO_READ_RATE (DISK READ)
481 The I/O rate of read(2) in bytes per second, for the process.
482 IO_WRITE_RATE (DISK WRITE)
484 The I/O rate of write(2) in bytes per second, for the process.
485 IO_RATE (DISK R/W)
487 The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
488 CGROUP
490 Which cgroup the process is in. For a shortened view see the CC‐
491 GROUP column below.
492 CCGROUP
494 Shortened view of the cgroup name that the process is in. This
495 performs some pattern-based replacements to shorten the displayed
496 string and thus condense the information.
497 /*.slice is shortened to /[*] (exceptions below)
498 /system.slice is shortened to /[S]
499 /user.slice is shortened to /[U]
500 /user-*.slice is shortened to /[U:*] (directly preceding /[U]
501 before dropped)
502 /machine.slice is shortened to /[M]
503 /machine-*.scope is shortened to /[SNC:*] (SNC: systemd nspawn
504 container), uppercase for the monitor
505 /lxc.monitor.* is shortened to /[LXC:*]
506 /lxc.payload.* is shortened to /[lxc:*]
507 /*.scope is shortened to /!*
508 /*.service is shortened to /* (suffix removed)
509 Encountered escape sequences (e.g. from systemd) inside the cgroup
511 name are not decoded.
512 OOM OOM killer score.
514 CTXT Incremental sum of voluntary and nonvoluntary context switches.
516 IO_PRIORITY (IO)
518 The I/O scheduling class followed by the priority if the class
519 supports it:
520 R for Realtime
521 B for Best-effort
522 id for Idle
523 PERCENT_CPU_DELAY (CPUD%)
525 The percentage of time spent waiting for a CPU (while runnable).
526 Requires CAP_NET_ADMIN.
527 PERCENT_IO_DELAY (IOD%)
529 The percentage of time spent waiting for the completion of syn‐
530 chronous block I/O. Requires CAP_NET_ADMIN.
531 PERCENT_SWAP_DELAY (SWAPD%)
533 The percentage of time spent swapping in pages. Requires
534 CAP_NET_ADMIN.
535 AGRP The autogroup identifier for the process. Requires Linux CFS to be
537 enabled.
538 ANI The autogroup nice value for the process autogroup. Requires Linux
540 CFS to be enabled.
541 All other flags
543 Currently unsupported (always displays '-').
544
546 While htop depends on most of the libraries it uses at build time there
547 are two noteworthy exceptions to this rule. These exceptions both re‐
548 late to data displayed in meters displayed in the header of htop and
549 were intentionally created as optional runtime dependencies instead.
550 These exceptions are described below:
551 libsystemd
553 The bindings for libsystemd are used in the SystemD meter to de‐
554 termine the number of active services and the overall system
555 state. Looking for the functions to determine these information
556 at runtime allows for builds to support these meters without
557 forcing the package manager to install these libraries on sys‐
558 tems that otherwise don't use systemd.
559 Summary: no build time dependency, optional runtime dependency
561 on libsystemd via dynamic loading, with systemctl(1) fallback.
562 libsensors
564 The bindings for libsensors are used for the CPU temperature
565 readings in the CPU usage meters if displaying the temperature
566 is enabled through the setup screen. In order for htop to show
567 these temperatures correctly though, a proper configuration of
568 libsensors through its usual configuration files is assumed and
569 that all CPU cores correspond to temperature sensors from the
570 coretemp driver with core 0 corresponding to a sensor labelled
571 "Core 0". The package temperature may be given as "Package id
572 0". If missing it is inferred as the maximum value from the
573 available per-core readings.
574 Summary: build time dependency on libsensors(3) C header files,
576 optional runtime dependency on libsensors(3) via dynamic load‐
577 ing.
578
580 By default htop reads its configuration from the XDG-compliant path
581 ~/.config/htop/htoprc. The configuration file is overwritten by htop's
582 in-program Setup configuration, so it should not be hand-edited. If no
583 user configuration exists htop tries to read the system-wide configura‐
584 tion from /etc/pcp/htoprc and as a last resort, falls back to its hard
585 coded defaults.
586 You may override the location of the configuration file using the $HTO‐
588 PRC environment variable (so you can have multiple configurations for
589 different machines that share the same home directory, for example).
590 The pcp-htop utility makes use of htoprc in exactly the same way. In
592 addition, it supports additional configuration files allowing new me‐
593 ters and columns to be added to the display via the usual Setup func‐
594 tion, which will display additional Available Meters and Available Col‐
595 umn entries for each runtime configured meter or column.
596 These pcp-htop configuration files are read once at startup. The for‐
598 mat of these files is described in detail in the pcp-htop(5) manual
599 page.
600 This functionality makes available many thousands of Performance Co-Pi‐
602 lot metrics for display by pcp-htop, as well as the ability to display
603 custom metrics added at individual sites. Applications and services
604 instrumented using the OpenMetrics format https://openmetrics.io can
605 also be displayed by pcp-htop if the pmdaopenmetrics(1) component is
606 configured.
607
609 Memory sizes in htop are displayed in a human-readable form. Sizes are
610 printed in powers of 1024. (e.g., 1023M = 1072693248 Bytes)
611 The decision to use this convention was made in order to conserve
613 screen space and make memory size representations consistent throughout
614 htop.
615
617 proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
618
620 pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
621
623 htop was originally developed by Hisham Muhammad. Nowadays it is main‐
624 tained by the community at <htop@groups.io>.
625 pcp-htop is maintained as a collaboration between the <htop@groups.io>
627 and <pcp@groups.io> communities, and forms part of the Performance Co-
628 Pilot suite of tools.
629
631 Copyright © 2004-2019 Hisham Muhammad.
632 Copyright © 2020-2022 htop dev team.
633 License GPLv2+: GNU General Public License version 2 or, at your op‐
635 tion, any later version.
636 This is free software: you are free to change and redistribute it.
638 There is NO WARRANTY, to the extent permitted by law.
639Performance Co-Pilot 2022 HTOP(1)