OpenZFS on Linux and FreeBSD: what the openzfs/zfs repository actually gives you

What openzfs/zfs is, and who the repository is for

OpenZFS began on Solaris and is now maintained by the OpenZFS community. This repository holds the code for running it on Linux and FreeBSD. That sentence is doing more work than it looks like: the project is not a single-platform filesystem, and the repository is not the whole of OpenZFS either. The README points elsewhere for illumos, macOS and Windows, listing the OpenZFS site for "conference videos and info on other platforms". If your target is Windows, this repository is not your starting point.

The audience is narrower than "anyone who wants a filesystem". You are expected to be comfortable with kernel modules, with building or installing a distribution package that tracks your kernel, and with reading platform-specific documentation. The README's installation section is a single link to the Getting Started page. There is no quickstart, no copy-paste command, no supported one-liner. That is a deliberate posture: the project treats installation as a per-platform problem, because it is one.

What you get in exchange is a filesystem and volume manager in the same component. Pools, datasets and volumes come from one stack, and the repository layout confirms the scope: it ships the userland commands under cmd/, the kernel modules under module/, the man pages under man/, udev rules under udev/ and a test suite under tests/.

The support matrix is the real contract

The most concrete thing in the README is the list of what is supported, and it is worth reading as a contract rather than a compatibility note. On Linux, all longterm kernels from kernel.org are supported, and stable kernels are "usually supported in the next OpenZFS release". The named longterm kernels are 6.18, 6.12, 6.6, 6.1, 5.15 and 5.10. Read that as: if you run a stable kernel that landed after the last OpenZFS release, you may be waiting.

For distributions the list is explicit. RHEL and compatible systems on the full or maintenance support tracks: 8.10, 9.7, 10.1. Ubuntu LTS releases: 26.04 "Resolute", 24.04 "Noble", 22.04 "Jammy". Debian stable and LTS: 13 "Trixie", 12 "Bookworm", 11 "Bullseye". FreeBSD releases receiving security support: 15.1 and 14.4. Everything else falls under "generally, if a distribution is following an LTS kernel, it should work well".

That last sentence is the honest part and also the weak point. A rolling distribution that tracks a kernel newer than the newest longterm branch is outside the tested set, and the README does not pretend otherwise. If your platform is not on the list, you are running an untested combination and you own the consequences.

Installing OpenZFS on Ubuntu or Debian, and what the README leaves out

The README does not contain installation commands. It states that full documentation for installing OpenZFS on your operating system is on the Getting Started page, and that is where install steps live. There is no package name, no repository setup and no build sequence in the README, so this section cannot give you a command to copy. What it can do is tell you what to look at in the repository once the tools are on the machine.

The repository layout is the map. The userland commands live under cmd/, the kernel modules under module/, the manual pages under man/, the udev rules under udev/ and the test suite under tests/. If you build from source rather than installing a distribution package, configure.ac, Makefile.am and autogen.sh are the build entry points, and copy-builtin exists for building the module into a kernel tree. The README does not document any of those steps, so treat the Getting Started page as the only supported route.

After installing, the first real use is a pool and a dataset. The project's own man pages under man/ are where the command syntax and the flags are documented; the README does not print examples, so this article will not invent any. The practical sequence a new user follows is: confirm the tools are present, create a pool on a device with no data you need, create a dataset inside it, and take a snapshot before making changes. Each of those steps has a manual page in the repository, and each will refuse or warn when the target is already in use.

If a command reports that the kernel module is missing, the fix is on the platform's install page, not in this repository's README. That is the pattern to internalize: the repository is the code, and the Getting Started page is the operator's manual.

Where OpenZFS is the wrong tool

The clearest limitation is the support matrix itself. OpenZFS on Linux is a kernel module, and kernel modules track kernel internals. The README's own split between longterm kernels and stable kernels, and its note that stable kernels are usually supported in the next release, tells you there is a lag. On a distribution that ships a kernel ahead of the supported set, you are either waiting for a release or building against an untested target.

Memory is the second constraint, and it is the one people underestimate. The related search data around this project includes `openzfs zfs_arc_max`, which is the tunable for the ARC, the adaptive replacement cache. OpenZFS will use available memory for caching, and on a small machine or a container host you will end up tuning that limit. If your workload is a single small VM with a fixed memory budget, this is friction you do not get from a simpler filesystem.

Third, the repository is not a distribution. It contains configure.ac, Makefile.am, autogen.sh, copy-builtin, module/, cmd/, lib/, man/, udev/, tests/ and packaging directories under rpm/ and contrib/. That layout says you can build it. It does not say you should, and the README does not walk you through it. If you are not prepared to follow platform documentation and, when needed, read the test suite, you are in the wrong repository.

Finally, the licence. The README states OpenZFS is released under a CDDL license, with details in the NOTICE, LICENSE and COPYRIGHT files and the identifier `UCRL-CODE-235197`. The repository's licence field is reported as NOASSERTION, which means automated tooling will not classify it for you. Whether CDDL fits your product is a question for your own legal review, not something this article can settle.

OpenZFS against the ZFS lineage it came from

The obvious alternative is not a different filesystem but a different ZFS. Oracle ZFS is the closed continuation of the original Solaris line; OpenZFS is the community-maintained codebase, and this repository is the Linux and FreeBSD implementation of it. The practical difference is not feature naming but where you get fixes and how you install them. With OpenZFS you track a public repository, public releases and public mailing lists. With Oracle ZFS you track a vendor's Solaris releases.

On FreeBSD the comparison is different again, because FreeBSD ships ZFS as part of the base system. The README lists FreeBSD 15.1 and 14.4 as supported, so on those releases the filesystem arrives with the operating system rather than as a module you install against a kernel you chose. That is a materially simpler upgrade path than the Linux side, where the module and the kernel must agree.

The third comparison people ask about is against a conventional Linux filesystem. The trade is straightforward: you give up the ability to run on any kernel and any distribution, and you take on memory tuning, and in return you get pooling, checksums, snapshots and datasets as first-class operations rather than as layers bolted on top. If you do not need those operations, you are paying the compatibility cost for nothing.

Releases, upgrades and what maintenance actually costs

The repository publishes parallel release lines. The recent releases are zfs-2.4.4, zfs-2.3.9 and zfs-2.2.11, all dated 2026-08-21. Three maintained lines at once is the upgrade story in miniature: you pick a line, you stay on it, and you move when your kernel or distribution moves. The README's claim that stable kernels are usually supported in the next OpenZFS release is the constraint that drives that timing. Upgrading OpenZFS ahead of your kernel is a choice; upgrading your kernel ahead of OpenZFS is often not one, because the distribution does it for you.

The last push to the default branch was on 2026-09-19, and the repository is not archived. That tells you the codebase is receiving changes. It does not tell you that a given release line is suitable for your kernel, and it does not tell you that master is stable. If you are deploying, you want a tagged release, not the default branch.

The maintenance cost that the README does not quantify is the pool upgrade. ZFS pools carry a feature flag set, and a pool created or upgraded by a newer OpenZFS may not be usable by an older one. The README is silent on rollback, and the man/ directory is where the project documents the relevant commands. Before you upgrade, the thing to verify is whether you can still import the pool with the version you would fall back to, and that answer lives in the platform documentation, not here.

Licence-wise, the CDDL is a file-level copyleft licence, which is a different shape from the GPL that the Linux kernel uses. The README does not discuss the interaction. Treat that as an open question for your own review rather than something the repository resolves for you.

Editorial conclusion

Adopt openzfs/zfs when you control the kernel and want checksummed storage, snapshots and pooled volumes on a supported longterm kernel or a supported RHEL, Ubuntu, Debian or FreeBSD release. Do not adopt it if you need a filesystem you can drop onto an arbitrary kernel, or if you want the Windows port, which the README places outside this repository. Before installing, verify three things: your kernel or distribution appears in the README support list, the release you intend to build is zfs-2.4.4, zfs-2.3.9 or zfs-2.2.11 rather than an untagged master snapshot, and you have read the Getting Started page for your platform because the README itself contains no install commands.

Frequently asked questions

Official sources

1. Issues
2. openzfs/zfs on GitHub
3. Project website
4. README
5. Releases