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 O Hide containerized processes: prevent processes running in a con‐
249 tainer from being displayed in the process list. (This is a toggle
250 key.)
251 p Show full paths to running programs, where applicable. (This is a
253 toggle key.)
254 Z Pause/resume process updates.
256 m Merge exe, comm and cmdline, where applicable. (This is a toggle
258 key.)
259 Ctrl-L
261 Refresh: redraw screen and recalculate values.
262 Numbers
264 PID search: type in process ID and the selection highlight will be
265 moved to it.
266
268 The following columns can display data about each process. A value of
269 '-' in all the rows indicates that a column is unsupported on your sys‐
270 tem, or currently unimplemented in htop. The names below are the ones
271 used in the "Available Columns" section of the setup screen. If a dif‐
272 ferent name is shown in htop's main screen, it is shown below in paren‐
273 thesis.
274 Command
276 The full command line of the process (i.e. program name and argu‐
277 ments).
278 If the option 'Merge exe, comm and cmdline in Command' (toggled by
280 the 'm' key) is active, the executable path (/proc/[pid]/exe) and
281 the command name (/proc/[pid]/comm) are also shown merged with the
282 command line, if available.
283 The program basename is highlighted if set in the configuration.
285 Additional highlighting can be configured for stale executables
286 (cf. EXE column below).
287 COMM The command name of the process obtained from /proc/[pid]/comm, if
289 readable.
290 Requires Linux kernel 2.6.33 or newer.
292 EXE The abbreviated basename of the executable of the process, ob‐
294 tained from /proc/[pid]/exe, if readable. htop is able to read
295 this file on linux for ALL the processes only if it has the capa‐
296 bility CAP_SYS_PTRACE or root privileges.
297 The basename is marked in red if the executable used to run the
299 process has been replaced or deleted on disk since the process
300 started. The information is obtained by processing the contents of
301 /proc/[pid]/exe.
302 Furthermore the basename is marked in yellow if any library is re‐
304 ported as having been replaced or deleted on disk since it was
305 last loaded. The information is obtained by processing the con‐
306 tents of /proc/[pid]/maps.
307 When deciding the color the replacement of the main executable al‐
309 ways takes precedence over replacement of any other library. If
310 only the memory map indicates a replacement of the main exe‐
311 cutable, this will show as if any other library had been replaced
312 or deleted.
313 This additional color markup can be configured in the "Display Op‐
315 tions" section of the setup screen.
316 Displaying EXE requires CAP_SYS_PTRACE and PTRACE_MODE_READ_FS‐
318 CRED.
319 PID The process ID.
321 STATE (S)
323 The state of the process:
324 S for sleeping
325 I for idle (longer inactivity than sleeping on platforms that
326 distinguish)
327 R for running
328 D for disk sleep (uninterruptible)
329 Z for zombie (waiting for parent to read its exit status)
330 T for traced or suspended (e.g by SIGTSTP)
331 W for paging
332 PPID The parent process ID.
334 PGRP The process's group ID.
336 SESSION (SID)
338 The process's session ID.
339 TTY The controlling terminal of the process.
341 TPGID
343 The process ID of the foreground process group of the controlling
344 terminal.
345 MINFLT
347 The number of page faults happening in the main memory.
348 CMINFLT
350 The number of minor faults for the process's waited-for children
351 (see MINFLT above).
352 MAJFLT
354 The number of page faults happening out of the main memory.
355 CMAJFLT
357 The number of major faults for the process's waited-for children
358 (see MAJFLT above).
359 UTIME (UTIME+)
361 The user CPU time, which is the amount of time the process has
362 spent executing on the CPU in user mode (i.e. everything but sys‐
363 tem calls), measured in clock ticks.
364 STIME (STIME+)
366 The system CPU time, which is the amount of time the kernel has
367 spent executing system calls on behalf of the process, measured in
368 clock ticks.
369 CUTIME (CUTIME+)
371 The children's user CPU time, which is the amount of time the
372 process's waited-for children have spent executing in user mode
373 (see UTIME above).
374 CSTIME (CSTIME+)
376 The children's system CPU time, which is the amount of time the
377 kernel has spent executing system calls on behalf of all the
378 process's waited-for children (see STIME above).
379 PRIORITY (PRI)
381 The kernel's internal priority for the process, usually just its
382 nice value plus twenty. Different for real-time processes.
383 NICE (NI)
385 The nice value of a process, from 19 (low priority) to -20 (high
386 priority). A high value means the process is being nice, letting
387 others have a higher relative priority. The usual OS permission
388 restrictions for adjusting priority apply.
389 STARTTIME (START)
391 The time the process was started.
392 PROCESSOR (CPU)
394 The ID of the CPU the process last executed on.
395 M_VIRT (VIRT)
397 The size of the virtual memory of the process.
398 M_RESIDENT (RES)
400 The resident set size (text + data + stack) of the process (i.e.
401 the size of the process's used physical memory).
402 M_SHARE (SHR)
404 The size of the process's shared pages.
405 M_TRS (CODE)
407 The text resident set size of the process (i.e. the size of the
408 process's executable instructions).
409 M_DRS (DATA)
411 The data resident set size (data + stack) of the process (i.e. the
412 size of anything except the process's executable instructions).
413 M_LRS (LIB)
415 The library size of the process.
416 M_SWAP (SWAP)
418 The size of the process's swapped pages.
419 M_PSS (PSS)
421 The proportional set size, same as M_RESIDENT but each page is di‐
422 vided by the number of processes sharing it.
423 M_M_PSSWP (PSSWP)
425 The proportional swap share of this mapping, unlike M_SWAP this
426 does not take into account swapped out page of underlying shmem
427 objects.
428 ST_UID (UID)
430 The user ID of the process owner.
431 PERCENT_CPU (CPU%)
433 The percentage of the CPU time that the process is currently us‐
434 ing. This is the default way to represent CPU usage in Linux.
435 Each process can consume up to 100% which means the full capacity
436 of the core it is running on. This is sometimes called "Irix mode"
437 e.g. in top(1).
438 PERCENT_NORM_CPU (NCPU%)
440 The percentage of the CPU time that the process is currently using
441 normalized by CPU count. This is sometimes called "Solaris mode"
442 e.g. in top(1).
443 PERCENT_MEM (MEM%)
445 The percentage of memory the process is currently using (based on
446 the process's resident memory size, see M_RESIDENT above).
447 USER The username of the process owner, or the user ID if the name
449 can't be determined.
450 On Linux the username is highlighted if the process has elevated
452 privileges, i.e. if it has been started from binaries with file
453 capabilities set or retained Linux capabilities, via the ambient
454 set, after switching from the root user.
455 TIME (TIME+)
457 The time, measured in clock ticks that the process has spent in
458 user and system time (see UTIME, STIME above).
459 NLWP The number of Light-Weight Processes (=threads) in the process.
461 TGID The thread group ID.
463 CTID OpenVZ container ID, a.k.a virtual environment ID.
465 VPID OpenVZ process ID.
467 VXID VServer process ID.
469 RCHAR (RD_CHAR)
471 The number of bytes the process has read.
472 WCHAR (WR_CHAR)
474 The number of bytes the process has written.
475 SYSCR (RD_SYSC)
477 The number of read(2) syscalls for the process.
478 SYSCW (WR_SYSC)
480 The number of write(2) syscalls for the process.
481 RBYTES (IO_RBYTES)
483 Bytes of read(2) I/O for the process.
484 WBYTES (IO_WBYTES)
486 Bytes of write(2) I/O for the process.
487 CNCLWB (IO_CANCEL)
489 Bytes of cancelled write(2) I/O.
490 IO_READ_RATE (DISK READ)
492 The I/O rate of read(2) in bytes per second, for the process.
493 IO_WRITE_RATE (DISK WRITE)
495 The I/O rate of write(2) in bytes per second, for the process.
496 IO_RATE (DISK R/W)
498 The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
499 CGROUP
501 Which cgroup the process is in. For a shortened view see the CC‐
502 GROUP column below.
503 CCGROUP
505 Shortened view of the cgroup name that the process is in. This
506 performs some pattern-based replacements to shorten the displayed
507 string and thus condense the information.
508 /*.slice is shortened to /[*] (exceptions below)
509 /system.slice is shortened to /[S]
510 /user.slice is shortened to /[U]
511 /user-*.slice is shortened to /[U:*] (directly preceding /[U]
512 before dropped)
513 /machine.slice is shortened to /[M]
514 /machine-*.scope is shortened to /[SNC:*] (SNC: systemd nspawn
515 container), uppercase for the monitor
516 /lxc.monitor.* is shortened to /[LXC:*]
517 /lxc.payload.* is shortened to /[lxc:*]
518 /*.scope is shortened to /!*
519 /*.service is shortened to /* (suffix removed)
520 Encountered escape sequences (e.g. from systemd) inside the cgroup
522 name are not decoded.
523 OOM OOM killer score.
525 CTXT Incremental sum of voluntary and nonvoluntary context switches.
527 IO_PRIORITY (IO)
529 The I/O scheduling class followed by the priority if the class
530 supports it:
531 R for Realtime
532 B for Best-effort
533 id for Idle
534 PERCENT_CPU_DELAY (CPUD%)
536 The percentage of time spent waiting for a CPU (while runnable).
537 Requires CAP_NET_ADMIN.
538 PERCENT_IO_DELAY (IOD%)
540 The percentage of time spent waiting for the completion of syn‐
541 chronous block I/O. Requires CAP_NET_ADMIN.
542 PERCENT_SWAP_DELAY (SWAPD%)
544 The percentage of time spent swapping in pages. Requires
545 CAP_NET_ADMIN.
546 AGRP The autogroup identifier for the process. Requires Linux CFS to be
548 enabled.
549 ANI The autogroup nice value for the process autogroup. Requires Linux
551 CFS to be enabled.
552 All other flags
554 Currently unsupported (always displays '-').
555
557 While htop depends on most of the libraries it uses at build time there
558 are two noteworthy exceptions to this rule. These exceptions both re‐
559 late to data displayed in meters displayed in the header of htop and
560 were intentionally created as optional runtime dependencies instead.
561 These exceptions are described below:
562 libsystemd
564 The bindings for libsystemd are used in the SystemD meter to de‐
565 termine the number of active services and the overall system
566 state. Looking for the functions to determine these information
567 at runtime allows for builds to support these meters without
568 forcing the package manager to install these libraries on sys‐
569 tems that otherwise don't use systemd.
570 Summary: no build time dependency, optional runtime dependency
572 on libsystemd via dynamic loading, with systemctl(1) fallback.
573 libsensors
575 The bindings for libsensors are used for the CPU temperature
576 readings in the CPU usage meters if displaying the temperature
577 is enabled through the setup screen. In order for htop to show
578 these temperatures correctly though, a proper configuration of
579 libsensors through its usual configuration files is assumed and
580 that all CPU cores correspond to temperature sensors from the
581 coretemp driver with core 0 corresponding to a sensor labelled
582 "Core 0". The package temperature may be given as "Package id
583 0". If missing it is inferred as the maximum value from the
584 available per-core readings.
585 Summary: build time dependency on libsensors(3) C header files,
587 optional runtime dependency on libsensors(3) via dynamic load‐
588 ing.
589
591 By default htop reads its configuration from the XDG-compliant path
592 ~/.config/htop/htoprc. The configuration file is overwritten by htop's
593 in-program Setup configuration, so it should not be hand-edited. If no
594 user configuration exists htop tries to read the system-wide configura‐
595 tion from /etc/pcp/htoprc and as a last resort, falls back to its hard
596 coded defaults.
597 You may override the location of the configuration file using the $HTO‐
599 PRC environment variable (so you can have multiple configurations for
600 different machines that share the same home directory, for example).
601 The pcp-htop utility makes use of htoprc in exactly the same way. In
603 addition, it supports additional configuration files allowing new me‐
604 ters and columns to be added to the display via the usual Setup func‐
605 tion, which will display additional Available Meters and Available Col‐
606 umn entries for each runtime configured meter or column.
607 These pcp-htop configuration files are read once at startup. The for‐
609 mat of these files is described in detail in the pcp-htop(5) manual
610 page.
611 This functionality makes available many thousands of Performance Co-Pi‐
613 lot metrics for display by pcp-htop, as well as the ability to display
614 custom metrics added at individual sites. Applications and services
615 instrumented using the OpenMetrics format https://openmetrics.io can
616 also be displayed by pcp-htop if the pmdaopenmetrics(1) component is
617 configured.
618
620 Memory sizes in htop are displayed in a human-readable form. Sizes are
621 printed in powers of 1024. (e.g., 1023M = 1072693248 Bytes)
622 The decision to use this convention was made in order to conserve
624 screen space and make memory size representations consistent throughout
625 htop.
626
628 proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
629
631 pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
632
634 htop was originally developed by Hisham Muhammad. Nowadays it is main‐
635 tained by the community at <htop@groups.io>.
636 pcp-htop is maintained as a collaboration between the <htop@groups.io>
638 and <pcp@groups.io> communities, and forms part of the Performance Co-
639 Pilot suite of tools.
640
642 Copyright © 2004-2019 Hisham Muhammad.
643 Copyright © 2020-2023 htop dev team.
644 License GPLv2+: GNU General Public License version 2 or, at your op‐
646 tion, any later version.
647 This is free software: you are free to change and redistribute it.
649 There is NO WARRANTY, to the extent permitted by law.
650Performance Co-Pilot 2023 HTOP(1)