IOTOP(8)

💖 IOTOP(8) — the manual page bestie 💖

okay so this is iotop, from the System Manager's Manual section 8 (that's the admin-girlies section, iykyk). It's a simple top-like I/O monitor and honestly? iconic.

---

✨ NAME ✨

iotop — a simple top-like I/O monitor 🎀

---

🦋 SYNOPSIS 🦋

iotop [OPTIONS]

---

🌸 DESCRIPTION 🌸

okay so picture this: iotop sits there watching all the I/O usage info that the Linux kernel is spilling out (and it needs 2.6.20 or later, no old-kernel vibes allowed), and then it serves you a whole table of current I/O usage by processes or threads on your system. Main character energy fr.

But bestie, there's a prerequisites check 👑. At least these options need to be enabled in your Linux kernel build configuration:

• CONFIG_TASK_DELAY_ACCT
• CONFIG_TASK_IO_ACCOUNTING
• CONFIG_TASKSTATS
• CONFIG_VM_EVENT_COUNTERS

…and since Linux kernel 5.14, the kernel.task_delayacct sysctl needs to be enabled too. No cap, if those aren't on, this whole thing is not gonna slay. 💀

iotop shows you columns for the I/O bandwidth read and written by each process/thread during the sampling period. It also shows the percentage of time the thread/process spent while swapping in and while waiting on I/O. And for each process, its I/O priority (class/level) is right there. So much info, so pretty. ✨

Plus! the total I/O bandwidth read and written during the sampling period is displayed at the top of the interface. Let's break those numbers down because they lowkey trip people up:

• Total DISK READ and Total DISK WRITE values = the total read and write bandwidth between processes and kernel threads on the one side, and the kernel block device subsystem on the other.
• Current DISK READ and Current DISK WRITE values = the corresponding bandwidths for current disk I/O between the kernel block device subsystem and the underlying hardware (HDD, SSD, etc.).

So yeah, Total and Current values may not be equal at any given moment of time — that's because of data caching and I/O operations reordering happening inside the Linux kernel. It's not a bug, it's just the kernel being mysterious. 🧚

🎮 Keyboard shortcuts, the fun part 🎮

• left and right arrows → change the sorting
• r → reverse the sorting order
• o → toggle the --only option
• p → toggle the --processes option
• a → toggle the --accumulated option
• q → quit
• i → change the priority of a thread or a process's thread(s)
• any other key → forces a refresh 💅

---

💅 OPTIONS 💅

• --version — show the version number and exit. Bye! 👋
• -h, --help — show usage information and exit.
• -o, --only — only show processes or threads that are actually doing I/O, instead of showing all of them. You can dynamically toggle this by pressing o. Filtered, curated, obsessed.
• -b, --batch — turn on non-interactive mode. Super useful for logging I/O usage over time. 📝
• -n NUM, --iter=NUM — set the number of iterations before quitting (it never quits by default, it's committed like that). Most useful in non-interactive mode.
• -d SEC, --delay=SEC — set the delay between iterations in seconds (1 second by default). It accepts non-integer values such as 1.1 seconds, so go off with your decimals. 🍓
• -p PID, --pid=PID — a list of processes/threads to monitor (all by default).
• -u USER, --user=USER — a list of users to monitor (all by default).
• -P, --processes — only show processes. Normally iotop shows all threads.
• -a, --accumulated — show accumulated I/O instead of bandwidth. In this mode, iotop shows the amount of I/O processes have done since iotop started. ✨
• -k, --kilobytes — use kilobytes instead of a human friendly unit. This mode is useful when scripting the batch mode of iotop. Instead of choosing the most appropriate unit, iotop will display all sizes in kilobytes.
• -t, --time — add a timestamp on each line (this implies --batch). Each line will be prefixed by the current time. 🕐
• -q, --quiet — suppress some lines of header (this implies --batch). This option can be specified up to three times to remove header lines.
• --no-help — suppress the keyboard shortcuts help display.

And here's the quiet-mode lore, because the number of -qs literally changes what you get:

• -q → column names are only printed on the first iteration
• -qq → column names are never printed
• -qqq → the I/O summary is never printed

---

🌈 SEE ALSO 🌈

ionice(1), top(1), vmstat(1), atop(1), htop(1) — the whole friend group, go say hi 🫶

---

👑 AUTHOR 👑

iotop was written by Guillaume Chazarain. 🫶

This manual page was started by Paul Wise for the Debian project and is placed in the public domain.

---

cute little sign-off bestie: this page is from the System Manager's Manual, dated October 1, 2021, and it's filed under section 8. Take care of your kernel config and it'll take care of you 💖✨🎀