Identity

Property	Value
Binary	`iotop` (Python, upstream abandoned) or `iotop-c` (C rewrite, actively maintained)
Config	No persistent config — invoked directly
Logs	No persistent logs — output to terminal
Type	CLI tool
Install	`apt install iotop` / `dnf install iotop` (Python version); `apt install iotop-c` / `dnf install iotop-c` (C version)

Key Operations

Task	Command
Interactive mode (requires root)	`sudo iotop`
Show only processes with active I/O	`sudo iotop -o`
Non-interactive batch output	`sudo iotop -b`
Batch mode, only active, 5 iterations	`sudo iotop -b -o -n 5`
Accumulated I/O totals instead of rates	`sudo iotop -a`
Set refresh interval to 2 seconds	`sudo iotop -d 2`
Filter output to a specific PID	`sudo iotop -p 1234`
Filter output to a specific user	`sudo iotop -u www-data`
Show process arguments (full cmdline)	`sudo iotop -P`
Batch output to a file	`sudo iotop -b -o -n 10 > /tmp/io-snapshot.txt`
Capture 60 seconds of I/O at 2s intervals	`sudo iotop -b -o -d 2 -n 30`
Sort by read rate in interactive mode	press `r` while running
Quit interactive mode	press `q`

Symptom	Cause	Fix
`Permission denied` or no output	Not running as root	Prefix with `sudo`; or grant `CAP_SYS_ADMIN` to the binary
`iotop: command not found`	Package not installed	`apt install iotop-c` (preferred on modern distros)
`iotop` installed but exits immediately	Python version deprecated; kernel too new	Install `iotop-c` instead — it is the maintained fork
Kernel: `CONFIG_TASK_IO_ACCOUNTING not set`	Kernel compiled without per-task I/O accounting	Recompile kernel or use a distribution kernel; most modern distros enable this
FUSE filesystem I/O attributed to fuse process	FUSE kernel interface — all I/O passes through the fuse kernel helper	Identify the actual user-space FUSE process by PID from `-p` output
Loop devices or tmpfs showing high I/O	Backing files or memory-mapped operations; rarely the root cause	Check what is mounted on the loop device: `losetup -l`; tmpfs writes are expected

Requires root or CAP_SYS_ADMIN: iotop reads per-task I/O accounting from the kernel's taskstats interface, which requires elevated privilege. Running without root produces no output or an immediate permission error.
Python version is abandoned upstream: the original iotop is written in Python and has not been maintained since ~2016. On newer kernels it may crash or behave incorrectly. Prefer iotop-c, a C rewrite with the same interface and active maintenance.
Disk I/O only — not network: iotop shows block device reads and writes. Network I/O, pipe I/O, and socket traffic do not appear. Use nethogs or ss for network per-process stats.
FUSE filesystem attribution: I/O to FUSE-mounted filesystems (sshfs, rclone, etc.) appears under the FUSE kernel thread, not the user process initiating the access. The actual data mover is identified by correlating PID with the FUSE mount.
Batch mode is required for scripting: interactive mode uses terminal control codes unsuitable for logging or pipelines. Always use -b when capturing output to a file or piping to another tool.

See references/ for: