1IOTOP(8)                    System Manager's Manual                   IOTOP(8)
2
3
4

NAME

6       iotop - simple top-like I/O monitor
7

SYNOPSIS

9       iotop [OPTIONS]
10

DESCRIPTION

12       iotop  watches I/O usage information available in the Linux kernel (re‐
13       quires 2.6.20 or later) and displays a table of current  I/O  usage  by
14       processes  or  threads  on  the  system.  At  least the CONFIG_TASK_DE‐
15       LAY_ACCT,   CONFIG_TASK_IO_ACCOUNTING,   CONFIG_TASKSTATS   and    CON‐
16       FIG_VM_EVENT_COUNTERS  options  need to be enabled in your Linux kernel
17       build configuration.
18
19       Running iotop as non-root user is possible by adding the NET_ADMIN  ca‐
20       pability.  This can be done by e.g.:
21
22              $ sudo setcap 'cap_net_admin+eip' <path-to>/iotop
23
24       Be  warned  that this will also allow other users to run it and get ac‐
25       cess to information that normally should not be available to them.
26
27       iotop displays columns for the I/O bandwidth read and written  by  each
28       process/thread  during  the  sampling period. It also displays the per‐
29       centage of time the thread/process spent while swapping  in  and  while
30       waiting  on  I/O.  For  each process, its I/O priority (class/level) is
31       shown.
32
33       In addition, the total I/O bandwidth read and written during  the  sam‐
34       pling  period  are  displayed  at the top of the interface.  Total DISK
35       READ and Total DISK WRITE values represent total read and  write  band‐
36       width between processes and kernel threads on one side and kernel block
37       device subsystem on the other. While Current DISK READ and Current DISK
38       WRITE  values  represent  corresponding bandwidths for current disk I/O
39       between the kernel block device subsystem and the  underlying  hardware
40       (HDD,  SSD,  etc.).   Thus Total and Current values may not be equal at
41       any given moment of time due to data caching  and  I/O  operations  re‐
42       ordering that take place inside the Linux kernel.
43
44       Use  the left and right arrows to select the sort column, r or space to
45       reverse the sorting order, o to toggle the --only option (this uses the
46       visible values from the GRAPH column or the IO column in case the GRAPH
47       column is hidden), p to toggle the --processes option, a to toggle  the
48       --accumulated  option,  i  to  change  the  priority  of  a thread or a
49       process's thread, f to change filtering by UID/PID  (--user  and  --pid
50       options),  1-9  to toggle the visibility of the respective column, 0 to
51       show all columns, up/down arrows,  page-up/page-down/home/end  keys  to
52       scroll and q to quit.  Any unrecognized key will be ignored.
53
54       All  processes or threads that have exited are displayed grayed for the
55       same time as is visible in the GRAPH column or 3  seconds  when  it  is
56       hidden.  The invalid data points in the GRAPHS column are displayed in‐
57       verse or with letter x (see option --dead-x and x shortcut). When using
58       unicode  characters  each position contains two datapoints and only the
59       positions with two invalid data points are reversed.
60
61       It is possible for threads of a process to have different priority from
62       their main process. This is shown with ! in the PRIO column of the main
63       process as e.g. !be/4.
64
65       Threads activity is always aggregated with and shown  inside  the  main
66       process.
67
68       When  showing  threads, they always appear below their main process and
69       are sorted in the same way as the processes.
70
71       There are two ways to change the IO priority of a process or  thread  -
72       press i and use arrows to select the process or thread from the visible
73       ones on screen or press i and type its TID (PID and TID have  the  same
74       value  for  the  main  process).  Then use tab and arrows to change the
75       priority value and confirm with enter.  Shortcuts esc or q will  cancel
76       this mode.
77
78       To  change  the  UID and PID filters, press f and use tab to select the
79       UID or PID field, then type the numerical id or n to remove the  filter
80       and  confirm with enter.  Filtering is always done by TID because it is
81       unique. Note that for the main process PID is the same as TID.   Short‐
82       cuts esc or q will cancel this mode.
83

OPTIONS

85       -v, --version
86              Show the version number and exit
87
88       -h, --help
89              Show usage information and exit
90
91       -o, --only
92              Only  show  processes  or threads actually doing I/O, instead of
93              showing all processes or threads.  This can be dynamically  tog‐
94              gled by pressing o
95
96       -b, --batch
97              Turn on non-interactive mode.  Useful for logging I/O usage over
98              time
99
100       -n NUM, --iter=NUM
101              Set the number of iterations before quitting (never quit by  de‐
102              fault).  This is most useful in non-interactive mode
103
104       -d SEC, --delay=SEC
105              Set  the  delay  between  iterations in seconds (1 second by de‐
106              fault).  Accepts non-integer values such as 1.1 seconds
107
108       -p PID, --pid=PID
109              A process/thread id to monitor (all by default)
110
111       -u USER, --user=USER
112              A user id to monitor (all by default).  The value will always be
113              resolved  first  unless  it is prefixed by + in which case it is
114              threated as numeric only.  Values that do not resolve but appear
115              to be numeric are used as numeric
116
117       -P, --processes
118              Only  show  processes.  Normally  iotop  shows processes and all
119              threads
120
121       -a, --accumulated
122              Show accumulated I/O instead of bandwidth.  In this mode,  iotop
123              shows the amount of I/O processes have done since iotop started
124
125       -k, --kilobytes
126              Use  kilobytes  instead  of a human friendly unit.  This mode is
127              useful when scripting the  batch  mode  of  iotop.   Instead  of
128              choosing  the most appropriate unit iotop will display all sizes
129              in kilobytes
130
131       -t, --time
132              Add a timestamp on each line (implies --batch). Each  line  will
133              be prefixed by the current time
134
135       -c, --fullcmdline
136              Show processes' full file path and parameters
137
138       -1, --hide-pid
139              Hide PID/TID column
140
141       -2, --hide-prio
142              Hide PRIO column
143
144       -3, --hide-user
145              Hide USER column
146
147       -4, --hide-read
148              Hide DISK READ column
149
150       -5, --hide-write
151              Hide DISK WRITE column
152
153       -6, --hide-swapin
154              Hide SWAPIN column
155
156       -7, --hide-io
157              Hide IO column
158
159       -8, --hide-graph
160              Hide GRAPH column
161
162       -9, --hide-command
163              Hide COMMAND column
164
165       -q, --quiet
166              Suppress some lines of header (implies --batch). This option can
167              be specified up to three times to remove header lines
168              -q     column names are only printed on the first iteration,
169              -qq    column names are never printed,
170              -qqq   the I/O summary is never printed
171
172       -x, --dead-x
173              Show dead processes/threads with letter  x  instead  of  inverse
174              background
175

KEYBOARD SHORTCUTS

177       q, Q   Exit
178
179       <space>, r, R
180              Toggle sort order
181
182       <home> Scroll to the top of the list
183
184       <end>  Scroll to the bottom of the list
185
186       <page-up>
187              Scroll one screen up
188
189       <page-down>
190              Scroll one screen down
191
192       <up>   Scroll one line up
193
194       <down> Scroll one line down
195
196       <right>
197              Sort by next column
198
199       <left> Sort by previous column
200
201       o, O   Toggle showing only processes with IO activity
202
203       p, P   Toggle showing processes/threads
204
205       a, A   Toggle showing accumulated/current values
206
207       ?, h, H
208              Toggle showing shortcut help
209
210       c, C   Toggle showing full command line
211
212       1, 2, 3, 4, 5, 6, 7, 8, 9
213              Toggle  showing  the  column  (column  number corresponds to the
214              shortcut)
215
216       0      Show all columns
217
218       i, I   IOnice a process/thread (depends on process/thread display mode)
219
220       f, F   Change UID and PID filters
221
222       u, U   Toggle using Unicode/ASCII characters for pseudo graph
223
224       x, X   Toggle the display mode of exited processes/threads between let‐
225              ter x and inverse background
226
227       s, S   Toggle freeze of data collection
228

SEE ALSO

230       ionice(1), top(1), vmstat(1), atop(1), htop(1)
231

AUTHOR

233       The original Python iotop implementation was written by Guillaume Chaz‐
234       arain.  This rewrite in C was started in 2014  by  Vyacheslav  Trushkin
235       and  reworked  to include all missing features from the original Python
236       code and several new ones in 2020 and 2021 by Boian Bonev.
237
238       This manual page was started by Paul Wise for the Debian project and is
239       placed in the public domain.
240
241
242
243                               January 28, 2021                       IOTOP(8)
Impressum