1HTOP(1)                          User Commands                         HTOP(1)
2
3
4

NAME

6       htop, pcp-htop - interactive process viewer
7

SYNOPSIS

9       htop [-dCFhpustvH]
10       pcp htop [-dCFhpustvH] [--host/-h host]
11

DESCRIPTION

13       htop is a cross-platform ncurses-based process viewer.
14
15       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
21       Tasks  related to processes (killing, renicing) can be done without en‐
22       tering their PIDs.
23
24       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

COMMAND-LINE OPTIONS

30       Mandatory  arguments  to  long  options are mandatory for short options
31       too.
32
33       -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
39       -C --no-color --no-colour
40              Start htop in monochrome mode
41
42       -F --filter=FILTER
43              Filter processes by command
44
45       -h --help
46              Display a help message and exit
47
48       -p --pid=PID,PID...
49              Show only the given PIDs
50
51       -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
56       -u --user=USERNAME
57              Show only the processes of a given user
58
59       -U --no-unicode
60              Do not use unicode but ASCII characters for graph meters
61
62       -M --no-mouse
63              Disable support of mouse control
64
65       --readonly
66              Disable all system and process changing features
67
68       -V --version
69              Output version information and exit
70
71       -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
75       -H --highlight-changes=DELAY
76              Highlight new and old processes
77
78          --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

INTERACTIVE COMMANDS

86       The following commands are supported while in htop:
87
88       Up, Alt-k
89            Select  (highlight)  the  previous  process  in  the process list.
90            Scroll the list if necessary.
91
92       Down, Alt-j
93            Select (highlight) the next process in the  process  list.  Scroll
94            the list if necessary.
95
96       Left, Alt-h
97            Scroll the process list left.
98
99       Right, Alt-l
100            Scroll the process list right.
101
102       PgUp, PgDn
103            Scroll the process list up or down one window.
104
105       Home Scroll  to  the  top  of  the  process  list  and select the first
106            process.
107
108       End  Scroll to the bottom of the  process  list  and  select  the  last
109            process.
110
111       Ctrl-A, ^
112            Scroll  left to the beginning of the process entry (i.e. beginning
113            of line).
114
115       Ctrl-E, $
116            Scroll right to the end of the process entry (i.e. end of line).
117
118       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
123       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
128       U    Untag  all  processes  (remove  all tags added with the Space or c
129            keys).
130
131       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
135       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
139       w    Display the command line of the selected  process  in  a  separate
140            screen, wrapped onto multiple lines as needed.
141
142       x    Display  the  active file locks of the selected process in a sepa‐
143            rate screen.
144
145       F1, h, ?
146            Go to the help screen
147
148       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
154       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
160            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
164       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
169       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
175       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
179       F7, ]
180            Increase the selected process's  priority  (subtract  from  'nice'
181            value).  This can only be done by the superuser.
182
183       F8, [
184            Decrease the selected process's priority (add to 'nice' value)
185
186       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
190       Shift-F8, {
191            Decrease the selected process's autogroup priority (add  to  auto‐
192            group 'nice' value)
193
194       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
200       F10, q
201            Quit
202
203       I    Invert the sort order: if sort order is increasing, switch to  de‐
204            creasing, and vice-versa.
205
206       +, -, *
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
213       a (on multiprocessor machines)
214            Set CPU affinity: mark which CPUs a process is allowed to use.
215
216       u    Show only processes owned by a specified user.
217
218       N    Sort by PID.
219
220       M    Sort by memory usage (top compatibility key).
221
222       P    Sort by processor usage (top compatibility key).
223
224       T    Sort by time (top compatibility key).
225
226       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
232       K    Hide  kernel  threads: prevent the threads belonging the kernel to
233            be displayed in the process list. (This is a toggle key.)
234
235       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
240       p    Show  full paths to running programs, where applicable. (This is a
241            toggle key.)
242
243       Z    Pause/resume process updates.
244
245       m    Merge exe, comm and cmdline, where applicable. (This is  a  toggle
246            key.)
247
248       Ctrl-L
249            Refresh: redraw screen and recalculate values.
250
251       Numbers
252            PID search: type in process ID and the selection highlight will be
253            moved to it.
254

COLUMNS

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
263       Command
264            The  full command line of the process (i.e. program name and argu‐
265            ments).
266
267            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
272            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
276       Comm The command name of the process obtained from /proc/[pid]/comm, if
277            readable.
278
279       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
284            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
288       PID  The process ID.
289
290       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
299       PPID The parent process ID.
300
301       PGRP The process's group ID.
302
303       SESSION (SID)
304            The process's session ID.
305
306       TTY  The controlling terminal of the process.
307
308       TPGID
309            The  process ID of the foreground process group of the controlling
310            terminal.
311
312       MINFLT
313            The number of page faults happening in the main memory.
314
315       CMINFLT
316            The number of minor faults for the process's  waited-for  children
317            (see MINFLT above).
318
319       MAJFLT
320            The number of page faults happening out of the main memory.
321
322       CMAJFLT
323            The  number  of major faults for the process's waited-for children
324            (see MAJFLT above).
325
326       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
331       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
336       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
341       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
346       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
350       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
356       STARTTIME (START)
357            The time the process was started.
358
359       PROCESSOR (CPU)
360            The ID of the CPU the process last executed on.
361
362       M_VIRT (VIRT)
363            The size of the virtual memory of the process.
364
365       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
369       M_SHARE (SHR)
370            The size of the process's shared pages.
371
372       M_TRS (CODE)
373            The  text  resident  set size of the process (i.e. the size of the
374            process's executable instructions).
375
376       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
380       M_LRS (LIB)
381            The library size of the process.
382
383       M_SWAP (SWAP)
384            The size of the process's swapped pages.
385
386       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
390       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
395       ST_UID (UID)
396            The user ID of the process owner.
397
398       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
405       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
410       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
414       USER The  username  of  the  process  owner, or the user ID if the name
415            can't be determined.
416
417       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
421       NLWP The number of Light-Weight Processes (=threads) in the process.
422
423       TGID The thread group ID.
424
425       CTID OpenVZ container ID, a.k.a virtual environment ID.
426
427       VPID OpenVZ process ID.
428
429       VXID VServer process ID.
430
431       RCHAR (RD_CHAR)
432            The number of bytes the process has read.
433
434       WCHAR (WR_CHAR)
435            The number of bytes the process has written.
436
437       SYSCR (RD_SYSC)
438            The number of read(2) syscalls for the process.
439
440       SYSCW (WR_SYSC)
441            The number of write(2) syscalls for the process.
442
443       RBYTES (IO_RBYTES)
444            Bytes of read(2) I/O for the process.
445
446       WBYTES (IO_WBYTES)
447            Bytes of write(2) I/O for the process.
448
449       CNCLWB (IO_CANCEL)
450            Bytes of cancelled write(2) I/O.
451
452       IO_READ_RATE (DISK READ)
453            The I/O rate of read(2) in bytes per second, for the process.
454
455       IO_WRITE_RATE (DISK WRITE)
456            The I/O rate of write(2) in bytes per second, for the process.
457
458       IO_RATE (DISK R/W)
459            The I/O rate, IO_READ_RATE + IO_WRITE_RATE (see above).
460
461       CGROUP
462            Which cgroup the process is in.
463
464       OOM  OOM killer score.
465
466       CTXT Incremental sum of voluntary and nonvoluntary context switches.
467
468       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
475       PERCENT_CPU_DELAY (CPUD%)
476            The percentage of time spent waiting for a CPU  (while  runnable).
477            Requires CAP_NET_ADMIN.
478
479       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
483       PERCENT_SWAP_DELAY (SWAPD%)
484            The  percentage  of  time  spent  swapping  in   pages.   Requires
485            CAP_NET_ADMIN.
486
487       COMM The  command name for the process. Requires Linux kernel 2.6.33 or
488            newer.
489
490       EXE  The executable file of the process as reported by the kernel.  Re‐
491            quires CAP_SYS_PTRACE and PTRACE_MODE_READ_FSCRED.
492
493       AGRP The autogroup identifier for the process. Requires Linux CFS to be
494            enabled.
495
496       ANI  The autogroup nice value for the process autogroup. Requires Linux
497            CFS to be enabled.
498
499       All other flags
500            Currently unsupported (always displays '-').
501

EXTERNAL LIBRARIES

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
509       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
517              Summary: no build time dependency, optional  runtime  dependency
518              on libsystemd via dynamic loading, with systemctl(1) fallback.
519
520       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
532              Summary: build time dependency on libsensors(3) C header  files,
533              optional  runtime  dependency on libsensors(3) via dynamic load‐
534              ing.
535

CONFIG FILES

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/htoprc and as a last resort,  falls  back  to  its  hard
542       coded defaults.
543
544       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
548       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
554       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
558       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

MEMORY SIZES

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
569       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

SEE ALSO

574       proc(5), top(1), free(1), ps(1), uptime(1) and limits.conf(5).
575

SEE ALSO FOR PCP

577       pmdaopenmetrics(1), PCPIntro(1), PMAPI(3), and pcp-htop(5).
578

AUTHORS

580       htop was originally developed by Hisham Muhammad.  Nowadays it is main‐
581       tained by the community at <htop@groups.io>.
582
583       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
591       License GPLv2+: GNU General Public License version 2 or,  at  your  op‐
592       tion, any later version.
593
594       This  is  free  software:  you  are free to change and redistribute it.
595       There is NO WARRANTY, to the extent permitted by law.
596
597
598
599htop 3.1.1                           2021                              HTOP(1)
Impressum