ZPOOL-LIST(8)

ZPOOL-LIST 💖 the one where your pools spill the tea

okay bestie, gather round, because this is zpool-list from section 8 of the System Manager's Manual, and it's literally the command that tells you everything about your ZFS storage pools. list information about ZFS storage pools — that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

zpool list [-HgLpPv] [-j [--json-int, --json-pool-key-guid]]
      [-o property[,property]…] [-T u|d] [pool]… [interval [count]]

yes it's a lot of flags. no you don't need all of them. but we're covering every single one because that's what we do here. 🫶

---

🌸 DESCRIPTION 🌸

So here's the tea: this command lists the pools you name, and it gives you a health status plus space usage for each one. If you don't name any pools at all, it just lists all pools in the system — every last one, no gatekeeping. 👑

And then there's the fun part: if you hand it an interval, it's gonna print that info every interval seconds, over and over, until you kill it. (not me watching my pool stats like it's a livestream 😭). And if you also specify count, it'll behave and exit after count reports have been printed. so polite.

the flags, one by one, no skips 💅

• -j, --json [--json-int, --json-pool-key-guid] — shows the list of pools in JSON format. Specify --json-int to display the numbers in integer format instead of strings. Specify --json-pool-key-guid to set pool GUID as key for pool objects instead of pool names. (yes, this is the one that makes jq your bestie.)
• -g — displays vdev GUIDs instead of the normal device names. These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. iconic, honestly.
• -H — Scripted mode. Does not display headers, and separates fields by a single tab instead of arbitrary space. this is the one you want when a script is consuming the output, fr fr.
• -o property — a comma-separated list of properties to display. See the zpoolprops(7) manual page for a list of valid properties. The default list is name, size, allocated, free, checkpoint, expandsize, fragmentation, capacity, dedupratio, health, altroot.
• -L — displays real paths for vdevs, resolving all symbolic links. This can be used to look up the current block device name regardless of the /dev/disk path used to open it. detective work ✨
• -p — displays numbers in parsable (exact) values. no rounding, no cute little G suffix, just the raw truth.
• -P — displays full paths for vdevs instead of only the last component of the path. This can be used in conjunction with the -L flag. team them up, they slay together.
• -T u|d — displays a time stamp. Specify u for a printed representation of the internal representation of time. See time(1). Specify d for standard date format. See date(1).
• -v — Verbose statistics. Reports usage statistics for individual vdevs within the pool, in addition to the pool-wide statistics. per-vdev breakdown, we love to see it.

---

🦋 EXAMPLES 🦋

Example 1: Listing Available ZFS Storage Pools

The following command lists all available pools on the system. In this case, the pool zion is faulted due to a missing device. The results from this command are similar to the following:

# zpool list
NAME    SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
rpool  19.9G  8.43G  11.4G         -    33%    42%  1.00x  ONLINE  -
tank   61.5G  20.0G  41.5G         -    48%    32%  1.00x  ONLINE  -
zion       -      -      -         -      -      -      -  FAULTED -

zion is FAULTED bestie, somebody go check that missing device 😭

---

Example 2: Displaying expanded space on a device

The following command displays the detailed information for the pool data. This pool is comprised of a single raidz vdev where one of its devices increased its capacity by 10 GiB. In this example, the pool will not be able to utilize this extra capacity until all the devices under the raidz vdev have been expanded.

# zpool list -v data
NAME         SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
data        23.9G  14.6G  9.30G         -    48%    61%  1.00x  ONLINE  -
  raidz1    23.9G  14.6G  9.30G         -    48%
    sda         -      -      -         -      -
    sdb         -      -      -       10G      -
    sdc         -      -      -         -      -

see that lonely 10G under sdb? that's the expansion that can't be used yet. everybody has to grow together or nobody grows. raidz solidarity. 🌈

---

Example 3: Displaying expanded space on a device

(and yes, that heading is the exact same as Example 2 — no, I didn't typo it, that's genuinely what the page says. we move. 💀)

The following command lists all available pools on the system in JSON format.

# zpool list -j | jq
{
  "output_version": {
    "command": "zpool list",
    "vers_major": 0,
    "vers_minor": 1
  },
  "pools": {
    "tank": {
      "name": "tank",
      "type": "POOL",
      "state": "ONLINE",
      "guid": "15220353080205405147",
      "txg": "2671",
      "spa_version": "5000",
      "zpl_version": "5",
      "properties": {
        "size": {
          "value": "111G",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "allocated": {
          "value": "30.8G",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "free": {
          "value": "80.2G",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "checkpoint": {
          "value": "-",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "expandsize": {
          "value": "-",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "fragmentation": {
          "value": "0%",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "capacity": {
          "value": "27%",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "dedupratio": {
          "value": "1.00x",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "health": {
          "value": "ONLINE",
          "source": {
            "type": "NONE",
            "data": "-"
          }
        },
        "altroot": {
          "value": "-",
          "source": {
            "type": "DEFAULT",
            "data": "-"
          }
        }
      }
    }
  }
}

look at that structured gorgeousness. pipe it into jq and suddenly you're the main character of observability. 👑

---

🎀 SEE ALSO 🎀

• zpool-import(8)
• zpool-status(8)

go read those next, they're the supporting cast and they eat too. 🫶

---

and that's a wrap, bestie 💖 this page is from OpenZFS, dated October 12, 2024, and it's ZPOOL-LIST(8). no cap, that's the whole thing. now go check your pool health, she's been waiting. 🦋✨