ZPOOL-TRIM(8)

💖 ZPOOL-TRIM 💖

okay bestie, welcome to zpool-trim — it's the System Manager's Manual page for the little command that starts a TRIM of free space in a ZFS storage pool. yes she's a real one. let's get into it ✨

---

🦋 NAME 🦋

zpool-trim — initiate TRIM of free space in ZFS storage pool

---

🌸 SYNOPSIS 🌸

zpool trim [-dw] [-r rate] [-c|-s] -a|pool [device]…

---

✨ DESCRIPTION ✨

So basically: this kicks off an immediate, on-demand TRIM operation across all the free space in a pool. what it's doing is telling the underlying storage devices about every single block in the pool that's no longer allocated anymore, which is literally how thinly provisioned devices get their space back. reclaiming, slay 💅

ngl the best part: you can run a manual on-demand TRIM whenever you want, totally regardless of the autotrim pool property setting. it does not care. it's not waiting for permission. fr fr. but do go read the docs for the autotrim property (up above) if you wanna know which types of vdev devices can actually be trimmed 👀

💅 OPTIONS 💅

• -a, --all — run the TRIM operation on all the pools. every last one 😌
• -d, --secure — this one starts a secure TRIM. when it's a secure TRIM, the device pinky-promises that the data sitting on the trimmed blocks has actually been erased. this needs the device to support it, and not all SSDs do — so it's giving "results may vary" energy. no cap 🙈
• -r, --rate rate — controls how fast the TRIM operation moves along. if you don't pass this, TRIM just goes as quickly as it possibly can (main character energy, zero chill). the rate is in bytes per second, it applies per vdev, and it can be set differently for each leaf vdev 🍓
• -c, --cancel — cancels trimming on the devices you name, or on all eligible devices if you name none. ⚠️ if one or more of the target devices is invalid or isn't currently being trimmed, the command fails and nothing gets cancelled on any device. it's all or nothing, bestie.
• -s, --suspend — suspends trimming on the specified devices, or all eligible devices if you didn't specify any. same deal as cancel: if one or more targets is invalid or not currently being trimmed, the command fails and no suspension happens on any device. then you can resume by running zpool trim with no flags on the relevant target devices 🫶
• -w, --wait — hang around until the devices are done being trimmed before returning. patience is a virtue ig 🧚

---

🌈 PERIODIC TRIM 🌈

On machines running systemd, you can enable trim timers per-pool. there are weekly and monthly timer units already provided, icons 💜

systemctl enable zfs-trim-weekly@rpool.timer --now

systemctl enable zfs-trim-monthly@otherpool.timer --now

On Debian systems there's an extra little bonus: a periodic TRIM runs for all online pools on the first Sunday of each month, and you don't have to enable any per-pool timer for it to happen. whether a given pool actually gets trimmed is controlled by the org.debian:periodic-trim user property on that pool's root dataset — and it accepts exactly three values:

• auto — which is the default, and it's the same as unset
• enable
• disable

and here's the tea on auto: in that mode, only devices whose TRIM support is known to be safe get trimmed. check /usr/share/doc/zfsutils-linux/README.Debian for the device classification rules and all the other details 👑

---

👀 SEE ALSO 👀

systemd.timer(5), zpoolprops(7), zpool-initialize(8), zpool-wait(8)

---

okay that's the whole page, you ate that 🎀 this was OpenZFS, dated July 30, 2025 — go trim something, but like, responsibly 💖✨