1IOTOP(8) System Manager's Manual IOTOP(8)
2
6 iotop - simple top-like I/O monitor
7
9 iotop [OPTIONS]
10
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 Running iotop as non-root user is possible by adding the NET_ADMIN ca‐
20 pability. This can be done by e.g.:
21 $ sudo setcap 'cap_net_admin+eip' <path-to>/iotop
23 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 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 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 any
41 given moment of time due to data caching and I/O operations reordering
42 that take place inside the Linux kernel.
43 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 cycle be‐
48 tween the --accumulated, --accum-bw and normal operation, i to change
49 the priority of a thread or a process's thread, f to change filtering
50 by UID/PID (--user and --pid options), 1-9 to toggle the visibility of
51 the respective column, 0 to show all columns, up/down arrows,
52 page-up/page-down/home/end keys to scroll and q to quit. Any unrecog‐
53 nized key will be ignored.
54 All processes or threads that have exited are displayed grayed for the
56 same time as is visible in the GRAPH column or 3 seconds when it is
57 hidden. The invalid data points in the GRAPHS column are displayed in‐
58 verse or with letter x (see option --dead-x and x shortcut). When using
59 unicode characters each position contains two datapoints and only the
60 positions with two invalid data points are reversed.
61 It is possible for threads of a process to have different priority from
63 their main process. This is shown with ! in the PRIO column of the main
64 process as e.g. !be/4.
65 Threads activity is always aggregated with and shown inside the main
67 process.
68 When showing threads, they always appear below their main process and
70 are sorted in the same way as the processes.
71 There are two ways to change the IO priority of a process or thread -
73 press i and use arrows to select the process or thread from the visible
74 ones on screen or press i and type its TID (PID and TID have the same
75 value for the main process). Then use tab and arrows to change the pri‐
76 ority value and confirm with enter. Shortcuts esc or q will cancel this
77 mode.
78 To change the UID and PID filters, press f and use tab to select the
80 UID or PID field, then type the numerical id or n to remove the filter
81 and confirm with enter. Filtering is always done by TID because it is
82 unique. Note that for the main process PID is the same as TID. Short‐
83 cuts esc or q will cancel this mode.
84 Starting with Linux kernel 5.14.x task_delayacct is configurable at
86 runtime and set to off by default. This setting can be changed in in‐
87 teractive mode by the Ctrl-T shortcut. In batch mode a warning is
88 printed when the setting is OFF. From the command line this can be en‐
89 abled by:
90 $ sudo sysctl kernel.task_delayacct=1
92 and disabled again by:
94 $ sudo sysctl kernel.task_delayacct=0
96 It is advisable to keep this option off when not using this or another
98 monitoring program because when enabled it has some effect on system
99 performance.
100
102 -v, --version
103 Show the version number and exit
104 -h, --help
106 Show usage information and exit
107 -H, --help-type=TYPE
109 Set the type of interactive help shown. Accepted values for TYPE
110 are none, win and inline.
111 -o, --only
113 Only show processes or threads actually doing I/O, instead of
114 showing all processes or threads. This can be dynamically tog‐
115 gled by pressing o
116 --no-only
118 Show all processes or threads
119 -b, --batch
121 Turn on non-interactive mode. Useful for logging I/O usage over
122 time
123 -n NUM, --iter=NUM
125 Set the number of iterations before quitting (never quit by de‐
126 fault). This is most useful in non-interactive mode
127 -d SEC, --delay=SEC
129 Set the delay between iterations in seconds (1 second by de‐
130 fault). Accepts non-integer values such as 1.1 seconds
131 -p PID, --pid=PID
133 A process/thread id to monitor (all by default)
134 -u USER, --user=USER
136 A user id to monitor (all by default). The value will always be
137 resolved first unless it is prefixed by + in which case it is
138 treated as numeric only. Values that do not resolve but appear
139 to be numeric are used as numeric
140 -P, --processes
142 Only show processes. Normally iotop shows processes and all
143 threads
144 --no-processes
146 Show processes and all threads
147 -a, --accumulated
149 Show accumulated I/O instead of bandwidth. In this mode, iotop
150 shows the amount of I/O processes have done since the process or
151 iotop started. Note that this option and --accum-bw are exclu‐
152 sive and they will turn each other off
153 --no-accumulated
155 Show bandwidth (useful when changing config file with --write)
156 -A, --accum-bw
158 Show accumulated I/O as bandwidth for the whole sampling period.
159 In this mode, iotop shows the amount of I/O per second for the
160 whole period since the process or iotop started Note that this
161 option and --accumulated are exclusive and they will turn each
162 other off
163 --no-accum-bw
165 Show bandwidth (useful when changing config file with --write)
166 -k, --kilobytes
168 Use kilobytes instead of a human friendly unit. This mode is
169 useful when scripting the batch mode of iotop. Instead of choos‐
170 ing the most appropriate unit iotop will display all sizes in
171 kilobytes
172 --no-kilobytes
174 Use human friendly units
175 -t, --time
177 Add a timestamp on each line (implies --batch). Each line will
178 be prefixed by the current time
179 -c, --fullcmdline
181 Show processes' full file path and parameters
182 --no-fullcmdline
184 Show processes' names only
185 -1, --hide-pid
187 Hide PID/TID column
188 --show-pid
190 Show PID/TID column
191 -2, --hide-prio
193 Hide PRIO column
194 --show-prio
196 Show PRIO column
197 -3, --hide-user
199 Hide USER column
200 --show-user
202 Show USER column
203 -4, --hide-read
205 Hide DISK READ column
206 --show-read
208 Show DISK READ column
209 -5, --hide-write
211 Hide DISK WRITE column
212 --show-write
214 Show DISK WRITE column
215 -6, --hide-swapin
217 Hide SWAPIN column
218 --show-swapin
220 Show SWAPIN column
221 -7, --hide-io
223 Hide IO column
224 --show-io
226 Show IO column
227 -8, --hide-graph
229 Hide GRAPH column
230 --show-graph
232 Show GRAPH column
233 -9, --hide-command
235 Hide COMMAND column
236 --show-command
238 Show COMMAND column
239 -g TYPE, --grtype=TYPE
241 Set GRAPH column data source. Accepted values for TYPE are io,
242 r, w, rw and sw.
243 -R, --reverse-graph
245 Reverse GRAPH direction - show most recent values on the right
246 side
247 --no-reverse-graph
249 Do not reverse GRAPH direction - show most recent values on the
250 left side
251 -q, --quiet
253 Suppress some lines of header (implies --batch). This option can
254 be specified up to three times to remove header lines
255 -q column names are only printed on the first iteration,
256 -qq column names are never printed,
257 -qqq the I/O summary is never printed
258 -x, --dead-x
260 Show exited processes/threads with letter x instead of inverse
261 background
262 --no-dead-x
264 Show exited processes/threads with inverse background
265 -e, --hide-exited
267 Hide exited processes
268 --show-exited
270 Show exited processes
271 -l, --no-color
273 Do not colorize values
274 --color
276 Colorize values. This will override the effect of the environ‐
277 ment variable NO_COLOR when explicitly specified on the command
278 line.
279 --si Use SI units of 1000 when printing values. The default is non-SI
281 1024
282 --no-si
284 Use non-SI units of 1024 when printing values
285 --threshold=1..10
287 Set the threshold to switch to next unit. The default value is 2
288 --ascii
290 Disable using Unicode
291 --unicode
293 Use Unicode drawing chars
294 -W, --write
296 Merge the preceding options to the current config, save the con‐
297 fig and exit. Note that all options after this one will be ig‐
298 nored.
299
301 q, Q Exit
302 W Save current settings to configuration file in $HOME/.con‐
304 fig/iotop/iotoprc
305 D Reset all settings to their default values
307 <space>, r
309 Toggle sort order
310 <home> Scroll to the top of the list
312 <end> Scroll to the bottom of the list
314 <page-up>
316 Scroll one screen up
317 <page-down>
319 Scroll one screen down
320 <up> Scroll one line up
322 <down> Scroll one line down
324 <right>
326 Sort by next column
327 <left> Sort by previous column
329 <esc> Cancel ionice or filter selection. In case only the help window
331 is open then close it
332 o, O Toggle showing only processes with IO activity
334 p, P Toggle showing processes/threads
336 a, A Cycle showing accumulated/accum-bw/current values
338 ? Toggle showing inline help
340 h, H Toggle showing window help
342 c, C Toggle showing full command line
344 1, 2, 3, 4, 5, 6, 7, 8, 9
346 Toggle showing the column (column number corresponds to the
347 shortcut)
348 0 Show all columns
350 g, G Cycle GRAPH source (IO=IO, R=DISK READ , W=DISK WRITE, R+W=DISK
352 READ+DISK WRITE, SW=SWAPIN). Using g will cycle forward and G
353 will cycle backward.
354 R Toggle reverse GRAPH direction
356 i, I IOnice a process/thread (depends on process/thread display mode)
358 f, F Change UID and PID filters
360 u, U Toggle using Unicode/ASCII characters for pseudo graph
362 l, L Toggle colorizing values
364 x, X Toggle the display mode of exited processes/threads between let‐
366 ter x and inverse background
367 e, E Toggle the display of exited processes
369 s, S Toggle freeze of data collection
371 Ctrl-B, b
373 Toggle SI units
374 Ctrl-R, t
376 Cycle unit threshold
377 Ctrl-T Toggle task_delayacct kernel sysctl
379 Ctrl-L Redraw screen
381 / Change search regular expression. While the search regular ex‐
383 pression is being edited, there is an indicator next to it that
384 shows if the expression is valid. The search is confirmed by
385 <enter> or cancelled by <esc>.
386 List of shortcuts in the editor:
388 <esc> Cancel editing and remove the regular expression filter
390 <enter>
392 Confirm the current regular expression and exit edit
393 mode. In case the regular expression is empty or invalid
394 it will match everything.
395 Alt/Meta-<backspace>, Ctrl-W
397 Delete one word from cursor to the left
398 Alt/Meta-D
400 Delete one word from cursor to the right
401 Alt/Meta-B, Ctrl-<left>
403 Move the cursor to the beginning of the word on the left
404 Alt/Meta-F, Ctrl-<right>
406 Move the cursor after the end of the word on the right
407 Ctrl-A, <home>
409 Move the cursor to the leftmost position
410 Ctrl-E, <end>
412 Move the cursor after the last character
413 Ctrl-B, <left>
415 Move the cursor to the left
416 Ctrl-F, <right>
418 Move the cursor to the right
419 Ctrl-H, <backspace>
421 Delete the character left of cursor
422 Ctrl-D, <del>
424 Delete the character under the cursor
425 Ctrl-K Delete from the character under the cursor to the end of
427 the line
428 Ctrl-U Delete everything
430 [anything-else]
432 Non-printable characters are ignored. Normal characters
433 are inserted before the character under the cursor. UTF-8
434 sequences are parsed and treated as a single character.
435 Unicode combining characters will be appended to the
436 character under the cursor.
437
439 As per the recommendation of https://www.no-color.org/ iotop honors the
440 contents of the environment variable NO_COLOR and when it is set to a
441 non empty string, all color output is suppressed.
442
444 ionice(1), top(1), vmstat(1), atop(1), htop(1)
445
447 The original Python iotop implementation was written by Guillaume Chaz‐
448 arain. This rewrite in C was started in 2014 by Vyacheslav Trushkin
449 and reworked to include all missing features from the original Python
450 code and several new ones from 2020 to 2023 by Boian Bonev.
451 This manual page was started by Paul Wise for the Debian project and is
453 placed in the public domain.
454 January 22, 2023 IOTOP(8)