IOTOP(8)

✨ NAME ✨

iotop(8) — simple top-like I/O monitor. Okay so bestie, this is the manual page for <rainbow>iotop</rainbow>: the top-like monitor that watches your I/O. It's giving system observability, no cap. 💅

🌸 SYNOPSIS 🌸

iotop [OPTIONS]

Yep, that's the whole summoning spell. You pass options. Slay. 🫶

💖 DESCRIPTION 💖

iotop watches I/O usage information available in the Linux kernel (requires 2.6.20 or later) and displays a table of current I/O usage by processes or threads on the system. 🦋 For this to even work, at least the CONFIG_TASK_DELAY_ACCT, CONFIG_TASK_IO_ACCOUNTING, CONFIG_TASKSTATS and CONFIG_VM_EVENT_COUNTERS options need to be enabled in your Linux kernel build configuration. No config, no data, periodt.

Running iotop as non-root user is possible by adding the NET_ADMIN capability. This can be done by e.g.:

$ sudo setcap 'cap_net_admin+eip' <path-to>/iotop

⚠️ Be warned that this will also allow other users to run it and get access to information that normally should not be available to them. This is not a cute little permission sprinkle — it's a whole access pass, so be careful.

iotop displays columns for the I/O bandwidth read and written by each process/thread during the sampling period. It also displays the percentage of time the thread/process spent while swapping in and while waiting on I/O. For each process, its I/O priority (class/level) is shown. 👑

In addition, the total I/O bandwidth read and written during the sampling period are displayed at the top of the interface. Total DISK READ and Total DISK WRITE values represent total read and write bandwidth between processes and kernel threads on one side and kernel block device subsystem on the other. While Current DISK READ and Current DISK WRITE values represent corresponding bandwidths for current disk I/O between the kernel block device subsystem and the underlying hardware (HDD, SSD, etc.). Thus Total and Current values may not be equal at any given moment of time due to data caching and I/O operations reordering that take place inside the Linux kernel. ✨

Now the keyboard lore, bestie. Use the left and right arrows to select the sort column, r or space to reverse the sorting order, o to toggle the --only option (this uses the visible values from the GRAPH column or the IO column in case the GRAPH column is hidden), p to toggle the --processes option, a to cycle between the --accumulated, --accum-bw and normal operation, i to change the priority of a thread or a process's thread, f to change filtering by UID/PID (--user and --pid options), 1-9 to toggle the visibility of the respective column, v to toggle the visibility of the VFS READ and VFS WRITE columns, 0 to show all columns, up/down arrows, page-up/page-down/home/end keys to scroll and q to quit. Any unrecognized key will be ignored. 💀

All processes or threads that have exited are displayed grayed for as long as their data is visible in the GRAPH column, or for two refresh cycles when it is hidden. The invalid data points in the GRAPH column are displayed inverse or with letter x (see option --dead-x and x shortcut). When using Unicode characters each position contains two datapoints and only the positions with two invalid data points are reversed. 🌈

It is possible for threads of a process to have different priority from their main process. This is shown with ! in the PRIO column of the main process as e.g. !be/4. 😭

With -P the values of a process include all its threads. When showing threads, the row of the main process shows only the values of the main thread.

When showing threads, they appear below their main process, unless they are listed alone with --flat. The processes are sorted by the values of the whole process and the threads of each process by their own values.

There are two ways to change the IO priority of a process or thread — press i and use arrows to select the process or thread from the visible ones on screen, or press i and type its TID (PID and TID have the same value for the main process). Then use tab and arrows to change the priority value and confirm with enter. Shortcuts esc or q will cancel this mode.

To change the UID and PID filters, press f and use tab to select the UID or PID field, then type the numerical id or n to remove the filter and confirm with enter. Filtering is always done by TID because it is unique. Note that for the main process PID is the same as TID. Shortcuts esc or q will cancel this mode.

Starting with Linux kernel 5.14.x task_delayacct is configurable at runtime and set to off by default. This setting can be changed in interactive mode by the Ctrl-T shortcut. In batch mode a warning is printed when the setting is OFF. From the command line this can be enabled by:

$ sudo sysctl kernel.task_delayacct=1

and disabled again by:

$ sudo sysctl kernel.task_delayacct=0

It is advisable to keep this option off when not using this or another monitoring program because when enabled it has some effect on system performance. 🌸

✨ OPTIONS ✨

okay bestie, this is the big one — every single flag iotop has, no skips, no shortcuts. buckle up 💖

• -v, --version — prints the version number and dips out. that's it, that's the whole job 💅
• -h, --help — shows you the usage info and exits. when you're lost, this is your girl 🫶
• -H, --help-type=TYPE — picks which flavor of interactive help you get. accepted values for TYPE: none, win, and inline. choose your own adventure ✨
• -o, --only — only shows processes or threads that are actually doing I/O, instead of every single process or thread. you can flip this on and off live by smashing o 🔥
• --no-only — shows all processes or threads. the "everyone's invited" mode 🎀
• -b, --batch — turns on non-interactive mode. absolutely iconic for logging I/O usage over time. the columns of non-interactive mode are fixed so the output can be parsed, meaning: the options that hide or show columns (including ones from the config file) apply only to the interactive view — with one exception, the VFS READ and VFS WRITE columns 👑
• -n NUM, --iter=NUM — sets the number of iterations before quitting (by default it never quits, fr fr). this is mostly useful in non-interactive mode.
• -d SEC, --delay=SEC — sets the delay between iterations in seconds (1 second by default). it accepts non-integer values, so go wild with like 1.1 seconds ⏱️
• -p PID, --pid=PID — a process/thread id to monitor (all by default). in non-interactive mode, only the tasks of its process are read, which is much faster on systems with many tasks — but heads up, the Total DISK READ and Total DISK WRITE then cover only that process 💀
• -u USER, --user=USER — a user id to monitor (all by default). it gets matched against the real user id of the tasks, which is what the USER column shows. the value will always be resolved first, unless it's prefixed by +, in which case it's treated as numeric only. values that don't resolve but look numeric get used as numeric. no cap 🧠
• -P, --processes — only shows processes. normally iotop shows processes and all threads, so this is the "just the mains" setting.
• --threads — shows processes and all threads. the full ensemble cast 🌈
• --flat — lists the threads alone, sorted by their own values, instead of grouping them below their process. has no effect when only processes are shown, and no effect in batch mode — which always lists the threads alone anyway.
• --no-flat — lists the threads grouped below their process. nesting energy 🪆
• -a, --accumulated — shows accumulated I/O instead of bandwidth. in this mode iotop shows the amount of I/O processes have done since they started, or (with --no-lifetime) since iotop first saw them. ⚠️ note that this option and --accum-bw are exclusive — they will turn each other off.
• --no-accumulated — shows bandwidth. useful when you're changing the config file with --write.
• -A, --accum-bw — shows accumulated I/O as bandwidth for the whole sampling period. in this mode iotop shows the amount of I/O per second for the whole period since the process started, or (with --no-lifetime) since iotop first saw it. ⚠️ note that this option and --accumulated are exclusive — they will turn each other off.
• --no-accum-bw — shows bandwidth. useful when you're changing the config file with --write.
• --lifetime — accumulates the I/O of each process or thread since it started. this is the default. important nuance bestie: the kernel counts the I/O of each thread, so a process's total includes its threads that iotop saw, but not the threads that exited before. with --accum-bw the average is over the time since the process or thread started 🧚
• --no-lifetime — accumulates the I/O of each process or thread since iotop first saw it.
• -k, --kilobytes — use kilobytes instead of a human friendly unit. this mode is a lifesaver when scripting the batch mode of iotop — instead of picking the most appropriate unit, iotop will display all sizes in kilobytes 📏
• --no-kilobytes — use human friendly units. back to the vibes 🌸
• -t, --time, --timestamp — adds a timestamp on each line (this implies --batch). every line gets prefixed by the current time 🕐
• -c, --fullcmdline — shows processes' full file path and parameters. the whole receipts.
• --no-fullcmdline — shows processes' names only.
• -1, --hide-pid — hides the PID/TID column.
• --show-pid — shows the PID/TID column.
• -2, --hide-prio — hides the PRIO column.
• --show-prio — shows the PRIO column.
• -3, --hide-user — hides the USER column.
• --show-user — shows the USER column.
• -4, --hide-read — hides the DISK READ column.
• --show-read — shows the DISK READ column.
• --show-vfs-read — shows the VFS READ column.
• --hide-vfs-read — hides the VFS READ column.
• -5, --hide-write — hides the DISK WRITE column.
• --show-write — shows the DISK WRITE column.
• --show-vfs-write — shows the VFS WRITE column.
• --hide-vfs-write — hides the VFS WRITE column.
• --show-vfs — shows the VFS READ and VFS WRITE columns. two for one 🎀
• --hide-vfs — hides the VFS READ and VFS WRITE columns.
• -6, --hide-swapin — hides the SWAPIN column.
• --show-swapin — shows the SWAPIN column.
• -7, --hide-io — hides the IO column.
• --show-io — shows the IO column.
• -8, --hide-graph — hides the GRAPH column.
• --show-graph — shows the GRAPH column.
• -9, --hide-command — hides the COMMAND column.
• --show-command — shows the COMMAND column.
• -g TYPE, --grtype=TYPE — sets the GRAPH column data source. accepted values for TYPE: io, r, w, rw, and sw. pick your plot ✨
• -R, --reverse-graph — reverses the GRAPH direction — shows the most recent values on the right side.
• --no-reverse-graph — doesn't reverse the GRAPH direction — shows the most recent values on the left side.
• -q, --quiet — suppresses headers before each run (this implies --batch). you can specify this up to three times to suppress different header lines:
  • -q — column names are only printed on the first iteration
  • -qq — column names are never printed
  • -qqq — the I/O summary is never printed
• -x, --dead-x — shows exited processes/threads with the letter x instead of inverse background 💀
• --no-dead-x — shows exited processes/threads with inverse background.
• -e, --hide-exited — hides exited processes. they're gone, let them rest 🙈
• --show-exited — shows exited processes.
• -l, --no-color — do not colorize values. monochrome moment.
• --color — colorize values. this will override the effect of the environment variable NO_COLOR when it's explicitly specified on the command line 🌈
• -T, --hide-time — do not show the time clock in the upper right corner.
• --show-time — shows the time clock in the upper right corner.
• --si — use SI units of 1000 when printing values. the default is non-SI 1024.
• --no-si — use non-SI units of 1024 when printing values.
• --threshold=1..10 — sets the threshold to switch to the next unit. the default value is 2.
• --ascii — disables using Unicode. plain and simple.
• --unicode — uses Unicode drawing chars. the pretty lines 🎀
• -N, --inverse — uses the inverse interface (black on white).
• --no-inverse — uses the normal interface. useful when you're changing the config file with --write.
• --filter=REGEX — filters processes by TID and COMMAND. this will only show processes where the TID or COMMAND match the REGEX 🔍
• --uid2name=MODE — sets the UID-to-user-name resolution mode for the USER column. here's the tea: the USER column shows the real user id of a task, as the kernel reports it in taskstats — so a set-user-ID program shows the user that started it. accepted values for MODE:
  • always — always resolve UID to username using getpwuid(3)
  • none — do not resolve UID, show the numeric UID instead
  • cyclic — cache resolved usernames internally for each refresh cycle to avoid repetitive getpwuid(3) lookups
  • static — cache resolved usernames permanently across all refresh cycles, and this is the default. pro tip: Ctrl+L clears the cache 🧠
• -W, --write — merges the preceding options into the current config, saves the config, and exits. ⚠️ note that all options after this one will be ignored.
• --debug-write — like -W (--write), but writes the config (with the preceding options) to standard output instead of saving it, and exits. ⚠️ note that all options after this one will be ignored. and for real, do not use this in normal operation — this option is for debugging and testing only 🛠️

---

⌨️ KEYBOARD SHORTCUTS ⌨️

Before you @ me — yes, there are a LOT of these. But bestie, each one is a little gift. Learn three of them and you're already out here looking like the main character of your own terminal. 💅

• q, Q — Exit. Bye bestie, slay, go touch grass. 🦋
• W — Save your current settings to a config file, in a spot that respects the XDG Base Directory Specification. The path gets created for you if it's not there yet. And if something goes wrong creating or accessing that config file? You get a warning with the reason, and the config just… does not get saved. No silent failure shenanigans here. 🙈
  • $XDG_CONFIG_HOME/iotop/iotoprc — this one if the XDG_CONFIG_HOME environment variable is set and not empty.
  • $HOME/.config/iotop/iotoprc — this one if XDG_CONFIG_HOME is not set or is empty, but HOME is set and not empty.
  • And if neither of them is set and not empty? There is no configuration file. Periodt.
• D — Reset every setting back to its default values. Factory reset energy. ✨
• <space>, r — Toggle the sort order. Flip it, reverse it, iconic.
• <home> — Scroll to the top of the list. ⬆️
• <end> — Scroll to the bottom of the list. ⬇️
• <page-up> — Scroll one whole screen up.
• <page-down> — Scroll one whole screen down.
• <up> — Scroll up by a single line, delicate.
• <down> — Scroll down by a single line, also delicate.
• <right> — Sort by the next column.
• <left> — Sort by the previous column.
• <esc> — Cancel ionice, filter or search. But if it's only the help window that's open, then it just closes that. Context matters, iykyk.
• o, O — Toggle showing only processes that actually have IO activity. Quiet ones stay hidden.
• p, P — Toggle between showing processes vs threads.
• Ctrl-F — Toggle grouping threads underneath their process. So cozy, so organized. 🎀
• a, A — Cycle between showing accumulated / accum-bw / current values.
• Ctrl-A — Toggle whether it accumulates since the processes started, or since iotop first saw them.
• ? — Toggle the inline help. Right there in the middle of your screen. 👑
• h, H — Toggle showing the window help.
• <, > — Scroll the help window up and down for when it does not fit on the screen. (It often does not.)
• c, C — Toggle showing the full command line.
• 1, 2, 3, 4, 5, 6, 7, 8, 9 — Toggle showing that column — the column number lines up with the shortcut number you pressed. Cute and logical.
• 0 — Show all the columns at once. All of them. The whole buffet. 🌈
• g, G — Cycle the GRAPH source (IO=IO, R=DISK READ, W=DISK WRITE, R+W=DISK READ+DISK WRITE, SW=SWAPIN). Lowercase g cycles forward and capital G cycles backward.
• R — Toggle reverse GRAPH direction.
• i, I — IOnice a process/thread — which one you get depends on your process/thread display mode.
• f, F — Change the UID and PID filters.
• u, U — Toggle using Unicode vs ASCII characters for the pseudo graph. Unicode is pretty, ASCII is safe. 💜
• l, L — Toggle colorizing values.
• n, N — Toggle inverse interface, aka black on white. Chaotic but valid.
• x, X — Toggle how exited processes/threads are displayed: either the letter x or an inverse background.
• e, E — Toggle the display of exited processes.
• T — Toggle the display of the time clock in the upper right corner. 🕐
• s, S — Toggle freezing data collection. Pause time, bestie.
• Ctrl-B, b — Toggle SI units.
• Ctrl-R, t — Cycle the unit threshold.
• Ctrl-T — Toggle the task_delayacct kernel sysctl.
• Ctrl-L — Redraw the screen and clear the UID cache.
• / — Change the search regular expression. While you're editing it, there's an indicator right next to it showing whether the expression is valid. Confirm the search with <enter> or cancel it with <esc>.

🔍 shortcuts in the search editor 🔍

You are, lowkey, in a whole tiny editor now. Here's the cheat sheet:

• <esc> — Cancel editing and remove the regular expression filter entirely.
• <enter> — Confirm the current regular expression and exit edit mode. And if that regular expression is empty or invalid? It'll match everything. Chill of it honestly.
• Alt/Meta-<backspace>, Ctrl-W — Delete one word from the cursor to the left.
• Alt/Meta-D — Delete one word from the cursor to the right.
• Alt/Meta-B, Ctrl-<left> — Move the cursor to the beginning of the word on the left.
• Alt/Meta-F, Ctrl-<right> — Move the cursor to just after the end of the word on the right.
• Ctrl-A, <home> — Move the cursor to the leftmost position.
• Ctrl-E, <end> — Move the cursor to just after the last character.
• Ctrl-B, <left> — Move the cursor left.
• Ctrl-F, <right> — Move the cursor right.
• Ctrl-H, <backspace> — Delete the character left of the cursor.
• Ctrl-D, <del> — Delete the character sitting under the cursor.
• Ctrl-K — Delete from the character under the cursor all the way to the end of the line.
• Ctrl-U — Delete everything. Wipe it. 💀
• [anything-else] — Non-printable characters get ignored. Normal characters get inserted before the character under the cursor. UTF-8 sequences are parsed and treated as a single character. And Unicode combining characters get appended to the character under the cursor. Fancy, multilingual, we love to see it. 🌸

---

🌱 ENVIRONMENT 🌱

• NO_COLOR — As per the recommendation of https://www.no-color.org/, iotop honors the contents of the environment variable NO_COLOR, and when it's set to a non-empty string, all color output is suppressed. Also, heads up: the config file keeps the colors only when they differ from what it gives, so --write and W do not save it as a setting.
• HOME, XDG_CONFIG_HOME — Used to figure out the config file path. See the W shortcut above for the details.
• IOTOP_NO_RENICE — Disable the i shortcut. That means the user will not be able to change processes' nice values. (Watch out for your unprivileged friends with this one.)

---

👀 SEE ALSO 👀

ionice(1), top(1), vmstat(1), atop(1), htop(1), getpwuid(3)

Are they your competition or your besties? Por qué no los dos. 🫶

---

💖 AUTHOR 💖

The original Python iotop implementation was written by Guillaume Chazarain. This rewrite in C was started in 2014 by Vyacheslav Trushkin, and was reworked to include all the missing features from the original Python code plus several new ones since 2020 by Boian Bonev.

This manual page was started by Paul Wise for the Debian project and is placed in the public domain. Giving it away for free, so generous, so iconic. ✨

---

And that's a wrap on the whole page bestie!! 🌟 This lovely thing is version October 19, 2026 and it lives in section IOTOP(8). Go monitor them processes, you absolute legend. q to exit, drink some water, ily. 🎀💜