1HTOP(1) User Commands HTOP(1)
2
6 htop, 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
321 I for idle (longer inactivity than sleeping on platforms that
322 distinguish)
323 R for running
324 D for disk sleep (uninterruptible)
325 Z for zombie (waiting for parent to read its exit status)
326 T for traced or suspended (e.g by SIGTSTP)
327 W for paging
328 PPID The parent process ID.
330 PGRP The process's group ID.
332 SESSION (SID)
334 The process's session ID.
335 TTY The controlling terminal of the process.
337 TPGID
339 The process ID of the foreground process group of the controlling
340 terminal.
341 MINFLT
343 The number of page faults happening in the main memory.
344 CMINFLT
346 The number of minor faults for the process's waited-for children
347 (see MINFLT above).
348 MAJFLT
350 The number of page faults happening out of the main memory.
351 CMAJFLT
353 The number of major faults for the process's waited-for children
354 (see MAJFLT above).
355 UTIME (UTIME+)
357 The user CPU time, which is the amount of time the process has
358 spent executing on the CPU in user mode (i.e. everything but sys‐
359 tem calls), measured in clock ticks.
360 STIME (STIME+)
362 The system CPU time, which is the amount of time the kernel has
363 spent executing system calls on behalf of the process, measured in
364 clock ticks.
365 CUTIME (CUTIME+)
367 The children's user CPU time, which is the amount of time the
368 process's waited-for children have spent executing in user mode
369 (see UTIME above).
370 CSTIME (CSTIME+)
372 The children's system CPU time, which is the amount of time the
373 kernel has spent executing system calls on behalf of all the
374 process's waited-for children (see STIME above).
375 PRIORITY (PRI)
377 The kernel's internal priority for the process, usually just its
378 nice value plus twenty. Different for real-time processes.
379 NICE (NI)
381 The nice value of a process, from 19 (low priority) to -20 (high
382 priority). A high value means the process is being nice, letting
383 others have a higher relative priority. The usual OS permission
384 restrictions for adjusting priority apply.
385 STARTTIME (START)
387 The time the process was started.
388 PROCESSOR (CPU)
390 The ID of the CPU the process last executed on.
391 M_VIRT (VIRT)
393 The size of the virtual memory of the process.
394 M_RESIDENT (RES)
396 The resident set size (text + data + stack) of the process (i.e.
397 the size of the process's used physical memory).
398 M_SHARE (SHR)
400 The size of the process's shared pages.
401 M_TRS (CODE)
403 The text resident set size of the process (i.e. the size of the
404 process's executable instructions).
405 M_DRS (DATA)
407 The data resident set size (data + stack) of the process (i.e. the
408 size of anything except the process's executable instructions).
409 M_LRS (LIB)
411 The library size of the process.
412 M_SWAP (SWAP)
414 The size of the process's swapped pages.
415 M_PSS (PSS)
417 The proportional set size, same as M_RESIDENT but each page is di‐
418 vided by the number of processes sharing it.
419 M_M_PSSWP (PSSWP)
421 The proportional swap share of this mapping, unlike M_SWAP this
422 does not take into account swapped out page of underlying shmem
423 objects.
424 ST_UID (UID)
426 The user ID of the process owner.
427 PERCENT_CPU (CPU%)
429 The percentage of the CPU time that the process is currently us‐
430 ing. This is the default way to represent CPU usage in Linux.
431 Each process can consume up to 100% which means the full capacity
432 of the core it is running on. This is sometimes called "Irix mode"
433 e.g. in top(1).
434 PERCENT_NORM_CPU (NCPU%)
436 The percentage of the CPU time that the process is currently using
437 normalized by CPU count. This is sometimes called "Solaris mode"
438 e.g. in top(1).
439 PERCENT_MEM (MEM%)
441 The percentage of memory the process is currently using (based on
442 the process's resident memory size, see M_RESIDENT above).
443 USER The username of the process owner, or the user ID if the name
445 can't be determined.
446 TIME (TIME+)
448 The time, measured in clock ticks that the process has spent in
449 user and system time (see UTIME, STIME above).
450 NLWP The number of Light-Weight Processes (=threads) in the process.
452 TGID The thread group ID.
454 CTID OpenVZ container ID, a.k.a virtual environment ID.
456 VPID OpenVZ process ID.
458 VXID VServer process ID.
460 RCHAR (RD_CHAR)
462 The number of bytes the process has read.
463 WCHAR (WR_CHAR)
465 The number of bytes the process has written.
466 SYSCR (RD_SYSC)
468 The number of read(2) syscalls for the process.
469 SYSCW (WR_SYSC)
471 The number of write(2) syscalls for the process.
472 RBYTES (IO_RBYTES)
474 Bytes of read(2) I/O for the process.
475 WBYTES (IO_WBYTES)
477 Bytes of write(2) I/O for the process.
478 CNCLWB (IO_CANCEL)
480 Bytes of cancelled write(2) I/O.
481 IO_READ_RATE (DISK READ)
483 The I/O rate of read(2) in bytes per second, for the process.
484 IO_WRITE_RATE (DISK WRITE)
486 The I/O rate of write(2) in bytes per second, for the process.
487 IO_RATE (DISK R/W)
489 The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
490 CGROUP
492 Which cgroup the process is in. For a shortened view see the CC‐
493 GROUP column below.
494 CCGROUP
496 Shortened view of the cgroup name that the process is in. This
497 performs some pattern-based replacements to shorten the displayed
498 string and thus condense the information.
499 /*.slice is shortened to /[*] (exceptions below)
500 /system.slice is shortened to /[S]
501 /user.slice is shortened to /[U]
502 /user-*.slice is shortened to /[U:*] (directly preceding /[U]
503 before dropped)
504 /machine.slice is shortened to /[M]
505 /machine-*.scope is shortened to /[SNC:*] (SNC: systemd nspawn
506 container), uppercase for the monitor
507 /lxc.monitor.* is shortened to /[LXC:*]
508 /lxc.payload.* is shortened to /[lxc:*]
509 /*.scope is shortened to /!*
510 /*.service is shortened to /* (suffix removed)
511 Encountered escape sequences (e.g. from systemd) inside the cgroup
513 name are not decoded.
514 OOM OOM killer score.
516 CTXT Incremental sum of voluntary and nonvoluntary context switches.
518 IO_PRIORITY (IO)
520 The I/O scheduling class followed by the priority if the class
521 supports it:
522 R for Realtime
523 B for Best-effort
524 id for Idle
525 PERCENT_CPU_DELAY (CPUD%)
527 The percentage of time spent waiting for a CPU (while runnable).
528 Requires CAP_NET_ADMIN.
529 PERCENT_IO_DELAY (IOD%)
531 The percentage of time spent waiting for the completion of syn‐
532 chronous block I/O. Requires CAP_NET_ADMIN.
533 PERCENT_SWAP_DELAY (SWAPD%)
535 The percentage of time spent swapping in pages. Requires
536 CAP_NET_ADMIN.
537 AGRP The autogroup identifier for the process. Requires Linux CFS to be
539 enabled.
540 ANI The autogroup nice value for the process autogroup. Requires Linux
542 CFS to be enabled.
543 All other flags
545 Currently unsupported (always displays '-').
546
548 While htop depends on most of the libraries it uses at build time there
549 are two noteworthy exceptions to this rule. These exceptions both re‐
550 late to data displayed in meters displayed in the header of htop and
551 were intentionally created as optional runtime dependencies instead.
552 These exceptions are described below:
553 libsystemd
555 The bindings for libsystemd are used in the SystemD meter to de‐
556 termine the number of active services and the overall system
557 state. Looking for the functions to determine these information
558 at runtime allows for builds to support these meters without
559 forcing the package manager to install these libraries on sys‐
560 tems that otherwise don't use systemd.
561 Summary: no build time dependency, optional runtime dependency
563 on libsystemd via dynamic loading, with systemctl(1) fallback.
564 libsensors
566 The bindings for libsensors are used for the CPU temperature
567 readings in the CPU usage meters if displaying the temperature
568 is enabled through the setup screen. In order for htop to show
569 these temperatures correctly though, a proper configuration of
570 libsensors through its usual configuration files is assumed and
571 that all CPU cores correspond to temperature sensors from the
572 coretemp driver with core 0 corresponding to a sensor labelled
573 "Core 0". The package temperature may be given as "Package id
574 0". If missing it is inferred as the maximum value from the
575 available per-core readings.
576 Summary: build time dependency on libsensors(3) C header files,
578 optional runtime dependency on libsensors(3) via dynamic load‐
579 ing.
580
582 By default htop reads its configuration from the XDG-compliant path
583 ~/.config/htop/htoprc. The configuration file is overwritten by htop's
584 in-program Setup configuration, so it should not be hand-edited. If no
585 user configuration exists htop tries to read the system-wide configura‐
586 tion from /etc/htoprc and as a last resort, falls back to its hard
587 coded defaults.
588 You may override the location of the configuration file using the $HTO‐
590 PRC environment variable (so you can have multiple configurations for
591 different machines that share the same home directory, for example).
592 The pcp-htop utility makes use of htoprc in exactly the same way. In
594 addition, it supports additional configuration files allowing new me‐
595 ters and columns to be added to the display via the usual Setup func‐
596 tion, which will display additional Available Meters and Available Col‐
597 umn entries for each runtime configured meter or column.
598 These pcp-htop configuration files are read once at startup. The for‐
600 mat of these files is described in detail in the pcp-htop(5) manual
601 page.
602 This functionality makes available many thousands of Performance Co-Pi‐
604 lot metrics for display by pcp-htop, as well as the ability to display
605 custom metrics added at individual sites. Applications and services
606 instrumented using the OpenMetrics format https://openmetrics.io can
607 also be displayed by pcp-htop if the pmdaopenmetrics(1) component is
608 configured.
609
611 Memory sizes in htop are displayed in a human-readable form. Sizes are
612 printed in powers of 1024. (e.g., 1023M = 1072693248 Bytes)
613 The decision to use this convention was made in order to conserve
615 screen space and make memory size representations consistent throughout
616 htop.
617
619 proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
620
622 pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
623
625 htop was originally developed by Hisham Muhammad. Nowadays it is main‐
626 tained by the community at <htop@groups.io>.
627 pcp-htop is maintained as a collaboration between the <htop@groups.io>
629 and <pcp@groups.io> communities, and forms part of the Performance Co-
630 Pilot suite of tools.
631
633 Copyright © 2004-2019 Hisham Muhammad.
634 Copyright © 2020-2023 htop dev team.
635 License GPLv2+: GNU General Public License version 2 or, at your op‐
637 tion, any later version.
638 This is free software: you are free to change and redistribute it.
640 There is NO WARRANTY, to the extent permitted by law.
641htop 3.2.2 2023 HTOP(1)