Where Does ZFS Keep Its Pool Cache?
Where ZFS keeps its pool cache file on Linux, what the cachefile property changes, and FreeBSD differences.
Last updated
ZFS remembers imported pools in a binary cache file so boots skip scanning every block device. Linux uses the standard /etc path with a systemd unit importing listed pools. A per-pool property overrides the location or disables caching entirely.
The file is a binary nvlist, readable through zdb rather than editors. Missing caches degrade to device scanning instead of failing. Removable media and clusters set the property to none so pools never resurrect uninvited. Check the property before debugging boot imports.
Where ZFS stores this, by platform
/etc/zfs/zpool.cache
Binary nvlist of imported pools read by the import service at boot. Override per pool with the cachefile property or none. Inspect with zdb; scan devices when missing. FreeBSD uses its own boot path instead.
Frequently asked questions
how do I read the pool cache
Inspect with zdb without arguments to print the cached configuration. A stale or missing cache still allows discovery by device scanning. Import explicitly with a custom path when the property points elsewhere.
how do I stop a pool auto-importing
Set the pool cachefile property to none for removable or clustered pools that must not auto-import. Empty string restores the standard location. Explicit paths pair with matching import commands.
where is the cache on FreeBSD
FreeBSD keeps it under /boot/zfs instead of /etc/zfs, imported by rc scripts rather than systemd units. Concepts match: cache file, hostid, mount then share. Adjust paths in runbooks per OS.
Notice an outdated path? Let us know.