IOSTAT(1)

📦
version 12.8.0 · 7 versions
, in arch rolling, nixpkgs unstable

💅 IOSTAT(1) — like, the Linux User's Manual, but make it cute

okay bestie, buckle up — this is iostat, and she's from the Linux User's Manual, section 1. yes, that manual. 🎀

✨ NAME ✨

iostat — reports Central Processing Unit (CPU) statistics and input/output statistics for devices and partitions. both. at once. she multi-tasks. 💅

✨ SYNOPSIS ✨

iostat [ -c ] [ -d ] [ -h ] [ -k | -m | -G ] [ -N ] [ -s ] [ -t ] [ -U ]
[ -V ] [ -x ] [ -y ] [ -z ] [ --compact ] [ --dec={ 0 | 1 | 2 } ] [ { -f
| +f } directory ] [ -j { ID | LABEL | PATH | UUID | ... } ] [ -o JSON ]
[ [ -H ] -g group_name ] [ --human ] [ --pretty ] [ -p [ device[,...] |
ALL ] ] [ device [...] | ALL ] [ interval [ count ] ]

like, yes, that's a lot of brackets. she's flexible. she contains multitudes. 🦋

✨ DESCRIPTION ✨

so the whole point of iostat, fr fr, is monitoring your system's input/output device loading — she does this by watching how long your devices are actually active compared to their average transfer rates. and then she generates reports 📊 that you can use to change your system configuration so the input/output load is better balanced between your physical disks. she's literally a load-balancing therapist for your disks. and she ate. 🔥

okay so about the reports — this part matters, don't @ me:

  • The first report covers the time since the system was booted. UNLESS you used the -y option, in which case this first report is omitted. (not me skipping the intro, but make it -y 💀)
  • Each subsequent report covers the time since the previous report.
  • All statistics get reported every single time iostat runs. every. time. 👑

and what does a report actually look like, you ask? 🧚

  1. a CPU header row, followed by
  2. a row of CPU statistics. and on multiprocessor systems, those CPU stats are calculated system-wide as averages among all processors — so she's giving you the whole squad's average, not one quirky core.
  3. then a device header row shows up, followed by a line of statistics for each device that is configured. one line per device. slay.

now the timing params, bestie, pay attention:

  • interval — the amount of time in seconds between each report. that's it. that's the vibe check on timing. ⏱️
  • count — can be specified in conjunction with interval. if you do, the value of count determines the number of reports generated, at interval seconds apart. so like, how many, and how far apart. iconic.
  • If you specify interval without count? The iostat command generates reports continuously. forever. she will not stop. she has no off switch. 😭🌊
lowkey a warning: interval without count = infinite report mode. know what you're getting into before you type it, bestie 🫶

okay that's the setup, next parts have all the options and she has so many options 💖

✨ REPORTS ✨

okay so iostat lowkey just makes two kinds of reports and that's it — the CPU Utilization report and the Device Utilization report. Two icons, two vibes, let's go 💅

💖 CPU Utilization Report 🎀

this one's the first report that pops out when you run iostat. heads up for the multiprocessor girlies: on multiprocessor systems the CPU values are global averages among all processors, so you're seeing the whole squad's average, not each core's individual moment. it's giving group project energy 🫶

the report has this format:

  • %user — the percentage of CPU utilization that happened while executing at the user level (application). that's your apps doing their thing ✨
  • %nice — the percentage of CPU utilization that happened while executing at the user level with nice priority.
  • %system — the percentage of CPU utilization that happened while executing at the system level (kernel). kernel's turn to shine 👑
  • %iowait — the percentage of time that the CPU or CPUs were idle during which the system had an outstanding disk I/O request. so: bored but waiting on the disk 😭
  • %steal — the percentage of time spent in involuntary wait by the virtual CPU or CPUs while the hypervisor was servicing another virtual processor. you're literally being ghosted by your own hypervisor 💀
  • %idle — the percentage of time that the CPU or CPUs were idle and the system did not have an outstanding disk I/O request. fully chillin', no disk drama 🦋

🌸 Device Utilization Report 🌸

the second report, bestie. this one gives you stats on a per physical device or partition basis. block devices and partitions you want stats for can be entered right there on the command line 🎀

  • if you enter no device nor partition, then stats get displayed for every device used by the system — providing that the kernel maintains statistics for it. iykyk, kernel's choice 🙈
  • if you give the ALL keyword on the command line, then stats are displayed for every device defined by the system, including the ones that have never been used. the whole roster, no exclusions 👑

transfer rates are shown in 1024-byte blocks by default, unless the environment variable POSIXLY_CORRECT is set — in which case 512-byte blocks are used. ok periodt, know the difference 💅

the report may show the following fields, depending on the flags used (e.g. -x, -s and -k, -m or -G) — so like, not everything shows up every time, it's a vibe check on your flags:

  • Device: — this column gives the device (or partition) name as listed in the /dev directory. literally just the name, no cap.
  • tps — the number of transfers per second that were issued to the device. a transfer is an I/O request to the device. multiple logical requests can be combined into a single I/O request to the device. a transfer is of indeterminate size. so like, don't assume how big it is, because nobody knows 🌈
  • Blk_read/s (kB_read/s, MB_read/s, GB_read/s) — the amount of data read from the device expressed in a number of blocks (kibibytes, mebibytes, gibibytes) per second. blocks are equivalent to sectors and therefore have a size of 512 bytes. key detail, don't forget it ⭐
  • Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s, GB_wrtn/s) — the amount of data written to the device expressed in a number of blocks (kibibytes, mebibytes, gibibytes) per second.
  • Blk_dscd/s (kB_dscd/s, MB_dscd/s, GB_dscd/s) — the amount of data discarded for the device expressed in a number of blocks (kibibytes, mebibytes, gibibytes) per second. bye bestie 🗑️
  • Blk_w+d/s (kB_w+d/s, MB_w+d/s, GB_w+d/s) — the amount of data written to or discarded for the device expressed in a number of blocks (kibibytes, mebibytes, gibibytes) per second.
  • Blk_read (kB_read, MB_read, GB_read) — the total number of blocks (kibibytes, mebibytes, gibibytes) read.
  • Blk_wrtn (kB_wrtn, MB_wrtn, GB_wrtn) — the total number of blocks (kibibytes, mebibytes, gibibytes) written.
  • Blk_dscd (kB_dscd, MB_dscd, GB_dscd) — the total number of blocks (kibibytes, mebibytes, gibibytes) discarded.
  • Blk_w+d (kB_w+d, MB_w+d, GB_w+d) — the total number of blocks (kibibytes, mebibytes, gibibytes) written or discarded.
  • r/s — the number (after merges) of read requests completed per second for the device.
  • w/s — the number (after merges) of write requests completed per second for the device.
  • d/s — the number (after merges) of discard requests completed per second for the device.
  • f/s — the number (after merges) of flush requests completed per second for the device. this counts flush requests executed by disks. flush requests are not tracked for partitions. before being merged, flush operations are counted as writes. so many little caveats, but we love her 🫶
  • sec/s (kB/s, MB/s, GB/s) — the number of sectors (kibibytes, mebibytes, gibibytes) read from, written to or discarded for the device per second.
  • rsec/s (rkB/s, rMB/s, rGB/s) — the number of sectors (kibibytes, mebibytes, gibibytes) read from the device per second.
  • wsec/s (wkB/s, wMB/s, wGB/s) — the number of sectors (kibibytes, mebibytes, gibibytes) written to the device per second.
  • dsec/s (dkB/s, dMB/s, dGB/s) — the number of sectors (kibibytes, mebibytes, gibibytes) discarded for the device per second.
  • rqm/s — the number of I/O requests merged per second that were queued to the device.
  • rrqm/s — the number of read requests merged per second that were queued to the device.
  • wrqm/s — the number of write requests merged per second that were queued to the device.
  • drqm/s — the number of discard requests merged per second that were queued to the device.
  • %rrqm — the percentage of read requests merged together before being sent to the device.
  • %wrqm — the percentage of write requests merged together before being sent to the device.
  • %drqm — the percentage of discard requests merged together before being sent to the device.
  • areq-sz — the average size (in kibibytes) of the I/O requests that were issued to the device.
📌 Note: in previous versions, this field was known as avgrq-sz and was expressed in sectors. glow-up, honestly.
  • rareq-sz — the average size (in kibibytes) of the read requests that were issued to the device.
  • wareq-sz — the average size (in kibibytes) of the write requests that were issued to the device.
  • dareq-sz — the average size (in kibibytes) of the discard requests that were issued to the device.
  • await — the average time (in milliseconds) for I/O requests issued to the device to be served. this includes the time spent by the requests in queue and the time spent servicing them. both parts, bestie 😌
  • r_await — the average time (in milliseconds) for read requests issued to the device to be served. includes the time spent by the requests in queue and the time spent servicing them.
  • w_await — the average time (in milliseconds) for write requests issued to the device to be served. includes the time spent by the requests in queue and the time spent servicing them.
  • d_await — the average time (in milliseconds) for discard requests issued to the device to be served. includes the time spent by the requests in queue and the time spent servicing them.
  • f_await — the average time (in milliseconds) for flush requests issued to the device to be served. the block layer combines flush requests and executes at most one at a time. thus flush operations could be twice as long: wait for current flush request, then execute it, then wait for the next one. so yeah, queue theory but make it tragic 😭
  • aqu-sz — the average queue length of the requests that were issued to the device.
📌 Note: in previous versions, this field was known as avgqu-sz. another rebrand, we stan a rebrand 💅
  • %util — percentage of elapsed time during which I/O requests were issued to the device (bandwidth utilization for the device). device saturation occurs when this value is close to 100% for devices serving requests serially. but for devices serving requests in parallel, such as RAID arrays and modern SSDs, this number does not reflect their performance limits. big warning, don't come for her when your NVMe looks weird, she literally told you 🔥

✨ OPTIONS ✨

Okay bestie, here's the menu. Every flag, all of them, no skipping 💅

  • -c — shows the CPU utilization report.
  • --compact — tells iostat not to break the Device Utilization Report into sub-reports, so all the metrics get squished onto a single line. one line. that's the whole vibe.
  • -d — shows the device utilization report.
  • --dec={ 0 | 1 | 2 } — picks how many decimal places you want (0 to 2, and the default is 2).
  • -f directory, +f directory — points iostat at a different directory to read device stats from. The difference is lowkey important:
    • -f says only use the files in that alternative directory.
    • +f says use both the standard kernel files and the files in the alternative directory to read device statistics.

directory is a directory holding stats for devices managed in userspace. It may contain:

  • a "diskstats" file whose format matches the one in "/proc",
  • stats for individual devices in files whose format matches those in "/sys".

Specifically, these files inside directory may get used by iostat:

directory/block/device/stat
directory/block/device/partition/stat

partition files must have an entry in directory/dev/block/ directory, like:

directory/dev/block/major:minor --> ../../block/device/partition
  • -G — stats in gibibytes per second 🫶
  • -g group_name { device [...] | ALL } — shows stats for a whole group of devices. iostat reports stats for each individual device in the list, then a line of global stats for the group, displayed as group_name and made up of all the devices in the list. The ALL keyword means every block device the system defines gets included in the group.
  • -H — has to be used with -g, and it means only the global stats for the group get displayed — no per-device stats for the individual devices in the group 🙈
  • -h — literally the same as saying --human --pretty.
  • --human — prints sizes in human readable format (like 1.0k, 1.2M, etc.). The units shown with this option override any other default units (like kibibytes, sectors...) that come attached to the metrics.
  • -j { ID | LABEL | PATH | UUID | ... } [ device [...] | ALL ] — shows persistent device names. Keywords like ID, LABEL, etc. say what type of persistent name you want. These keywords aren't a limited set — the only prerequisite is that the directory with the required persistent names exists in /dev/disk. Optionally you can list multiple devices in the chosen persistent name type. And because persistent device names are usually long, --pretty is implicitly set with this option.
  • -k — stats in kibibytes per second.
  • -m — stats in mebibytes per second.
  • -N — shows the registered device mapper names for any device mapper devices. Useful for viewing LVM2 statistics 👑
  • -o JSON — spits the stats out in JSON (JavaScript Object Notation) format. Heads up: JSON output field order is undefined, and new fields may be added in the future. so don't get too attached to the ordering fr fr.
  • -p [ { device[,...] | ALL } ] — shows stats for block devices and all their partitions that the system is using. If you type a device name on the command line, then stats for it and all its partitions get displayed. And last, the ALL keyword means stats have to be displayed for all the block devices and partitions the system defines — including the ones that have never been used 💀. If -j is defined before this option, devices entered on the command line can be specified with the chosen persistent name type.
  • --pretty — makes the Device Utilization Report easier for a human to read. The device name gets printed on the right side. The report may also be broken into sub-reports if there are lots of metrics to display (use --compact to prevent that).
  • -s — shows a short (narrow) version of the report that should fit on screens 80 characters wide 🌸
  • -t — prints the time for each report displayed. The timestamp format may depend on the value of the S_TIME_FORMAT environment variable (peep below) and on whether -U was used.
  • -U — shows the timestamp (UTC — Coordinated Universal Time) in seconds from the epoch.
  • -V — prints the version number then exits.
  • -x — shows extended statistics.
  • -y — omits the first report (the one with stats since system boot) if you're displaying multiple records at a given interval.
  • -z — tells iostat to omit output for any devices that had no activity during the sample period.

🌈 ENVIRONMENT 🌈

iostat takes these environment variables into account, bestie:

POSIXLY_CORRECT

When this variable is set, transfer rates get shown in 512-byte blocks instead of the default 1024-byte blocks.

S_COLORS

By default, statistics are displayed in color when the output is connected to a terminal. Use this variable to change the settings. Possible values are never, always or auto (the last one is equivalent to the default settings).

💜 Please note that the color being used (red, yellow, or whatever) to display a value is not indicative of any kind of issue just because of the color. It only indicates different ranges of values. no cap, don't panic.

S_COLORS_SGR

Specifies the colors and other attributes used to display statistics on the terminal. Its value is a colon-separated list of capabilities that defaults to I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22. Supported capabilities:

  • I= — SGR (Select Graphic Rendition) substring for device names.
  • N= — SGR substring for non-zero statistics values.
  • W= (or M=) — SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the metric's meaning).
  • X= (or H=) — SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the metric's meaning).
  • Z= — SGR substring for zero values.

S_TIME_FORMAT

If this variable exists and its value is ISO then the current locale gets ignored when printing the date in the report header. The iostat command will use the ISO 8601 format (YYYY-MM-DD) instead. The timestamp displayed with option -t will also be compliant with ISO 8601 format ✨

🎀 EXAMPLES 🎀

  • iostat — display a single history since boot report for all CPU and Devices.
  • iostat -d 2 — display a continuous device report at two second intervals.
  • iostat -d 2 6 — display six reports at two second intervals for all devices.
  • iostat -x sda sdb 2 6 — display six reports of extended statistics at two second intervals for devices sda and sdb.
  • iostat -p sda 2 6 — display six reports at two second intervals for device sda and all its partitions (sda1, etc.)

💀 BUGS 💀

The /proc filesystem must be mounted for iostat to work. non-negotiable.

Kernels older than 2.6.x are no longer supported. sorry bestie, ancient kernel rights revoked.

And this one's iconic: although iostat displays units corresponding to kilobytes (kB), megabytes (MB), gigabytes (GB)..., it actually uses kibibytes (kiB), mebibytes (MiB), gibibytes (GiB)... A kibibyte is equal to 1024 bytes, a mebibyte is equal to 1024 kibibytes, and a gibibyte is equal to 1024 mebibytes. it's giving "technically the label is lying" but now you know 🙈

🦋 FILES 🦋

  • /proc/stat — contains system statistics.
  • /proc/uptime — contains system uptime.
  • /proc/diskstats — contains disks statistics.
  • /sys — contains statistics for block devices.
  • /proc/self/mountstats — contains statistics for network filesystems.
  • /dev/disk — contains persistent device names.

👑 AUTHOR 👑

Sebastien Godard (sysstat <at> orange.fr)

🌸 SEE ALSO 🌸

sar(1), pidstat(1), mpstat(1), vmstat(8), tapestat(1), nfsiostat(1), cifsiostat(1)

Okay that's the whole page, you're officially an iostat girlie now 🧚💖 This one's from the Linux fam, AUGUST 2026 edition, filed under IOSTAT(1) — go forth and -x responsibly, bestie 💅✨🍓

📦 where this page comes from