Custom Packages
The following instructions assume you are building from an official release tarball (version 0.8.0 or newer) or directly from the git repository. Most users should not need to do this and should preferentially use the distribution packages. As a general rule the distribution packages will be more tightly integrated, widely tested, and better supported. However, if your distribution of choice doesn’t provide packages, or you’re a developer and want to roll your own, here’s how to do it.
The first thing to be aware of is that the build system is capable of generating several different types of packages. Which type of package you choose depends on what’s supported on your platform and exactly what your needs are.
DKMS packages contain only the source code and scripts for rebuilding the kernel modules. When the DKMS package is installed kernel modules will be built for all available kernels. Additionally, when the kernel is upgraded new kernel modules will be automatically built for that kernel. This is particularly convenient for desktop systems which receive frequent kernel updates. The downside is that because the DKMS packages build the kernel modules from source a full development environment is required which may not be appropriate for large deployments.
kmods packages are binary kernel modules which are compiled against a specific version of the kernel. This means that if you update the kernel you must compile and install a new kmod package. If you don’t frequently update your kernel, or if you’re managing a large number of systems, then kmod packages are a good choice.
kABI-tracking kmod Packages are similar to standard binary kmods and may be used with Enterprise Linux distributions like Red Hat and CentOS. These distributions provide a stable kABI (Kernel Application Binary Interface) which allows the same binary modules to be used with new versions of the distribution provided kernel.
By default the build system will generate user packages and both DKMS and kmod style kernel packages if possible. The user packages can be used with either set of kernel packages and do not need to be rebuilt when the kernel is updated. You can also streamline the build process by building only the DKMS or kmod packages as shown below.
Be aware that when building directly from a git repository you must first run the autogen.sh script to create the configure script. This will require installing the GNU autotools packages for your distribution. To perform any of the builds, you must install all the necessary development tools and headers for your distribution.
It is important to note that if the development kernel headers for the currently running kernel aren’t installed, the modules won’t compile properly.
RHEL, CentOS and Fedora
Make sure that the required packages are installed to build the latest ZFS 2.1 release:
RHEL/CentOS 7:
sudo yum install epel-release gcc make autoconf automake libtool rpm-build libtirpc-devel libblkid-devel libuuid-devel libudev-devel openssl-devel zlib-devel libaio-devel libattr-devel elfutils-libelf-devel kernel-devel-$(uname -r) python python2-devel python-setuptools python-cffi libffi-devel ncompress
sudo yum install --enablerepo=epel dkms python-packaging
NOTE: RHEL/CentOS 7 is end of life. Use yum instead of dnf for install instructions below.
RHEL/CentOS 8:
sudo dnf install --skip-broken epel-release gcc make autoconf automake libtool rpm-build kernel-rpm-macros libtirpc-devel libblkid-devel libuuid-devel libudev-devel openssl-devel zlib-devel libaio-devel libattr-devel elfutils-libelf-devel kernel-devel-$(uname -r) kernel-abi-stablelists-$(uname -r | sed 's/\.[^.]\+$//') python3 python3-devel python3-setuptools python3-cffi libffi-devel ncompress
sudo dnf install --skip-broken --enablerepo=epel --enablerepo=powertools python3-packaging dkms
RHEL/CentOS 9:
sudo dnf config-manager --set-enabled crb
sudo dnf install --skip-broken epel-release gcc make autoconf automake libtool rpm-build kernel-rpm-macros libtirpc-devel libblkid-devel libuuid-devel libudev-devel openssl-devel zlib-devel libaio-devel libattr-devel elfutils-libelf-devel kernel-devel-$(uname -r) kernel-abi-stablelists-$(uname -r | sed 's/\.[^.]\+$//') python3 python3-devel python3-setuptools python3-cffi libffi-devel
sudo dnf install --skip-broken --enablerepo=epel python3-packaging dkms
Fedora 41:
sudo dnf install gcc make autoconf automake libtool rpm-build kernel-rpm-macros libtirpc-devel libblkid-devel libuuid-devel systemd-devel openssl-devel zlib-ng-compat-devel libaio-devel libattr-devel libffi-devel libunwind-devel kernel-devel-$(uname -r) python3 python3-devel openssl ncompress
sudo dnf install python3-packaging dkms
DKMS
Building rpm-based DKMS and user packages can be done as follows:
$ cd zfs
$ ./configure
$ make -j1 rpm-utils rpm-dkms
$ sudo dnf install *.$(uname -m).rpm *.noarch.rpm
kmod
The key thing to know when building a kmod package is that a specific Linux kernel must be specified. At configure time the build system will make an educated guess as to which kernel you want to build against. However, if configure is unable to locate your kernel development headers, or you want to build against a different kernel, you must specify the exact path with the –with-linux and –with-linux-obj options.
$ cd zfs
$ ./configure
$ make -j1 rpm-utils rpm-kmod
$ sudo dnf install *.$(uname -m).rpm *.noarch.rpm
NOTE: Fedora 41 Workstation includes the rpm package zfs-fuse which will prevent the installation of your own packages. Remove that single package before dnf install:
$ sudo rpm -e --nodeps zfs-fuse
kABI-tracking kmod
The process for building kABI-tracking kmods is almost identical to for building normal kmods. However, it will only produce binaries which can be used by multiple kernels if the distribution supports a stable kABI. In order to request kABI-tracking package the –with-spec=redhat option must be passed to configure.
NOTE: This type of package is not available for Fedora.
$ cd zfs
$ ./configure --with-spec=redhat
$ make -j1 rpm-utils rpm-kmod
$ sudo dnf install *.$(uname -m).rpm *.noarch.rpm
Fedora 41 secure boot with kmod
The zfs kernel module will fail to load on modern computers that use UEFI and secure boot:
$ sudo modprobe zfs
modprobe: ERROR: could not insert 'zfs': Key was rejected by service
Either disable secure boot or create a custom machine owner key (MOK) once and manually sign your current and future modules using that key:
$ sudo mkdir /etc/pki/mok
$ cd /etc/pki/mok
$ sudo openssl req -new -x509 -newkey rsa:2048 -keyout LOCALMOK.priv -outform DER -out LOCALMOK.der -nodes -days 36500 -subj "/CN=LOCALMOK/"
$ sudo mokutil --import LOCALMOK.der
Mokutil asks for a password that you have to create and remember, then reboot your machine and UEFI will ask to import your key:
Select "Enroll MOK", "Continue", "Yes", enter mokutil's password, "Reboot"
This MOK can then be used to manually sign your zfs kernel modules:
$ rpm -ql kmod-zfs-$(uname -r) | grep .ko
/lib/modules/6.11.8-300.fc41.x86_64/extra/zfs/spl.ko
/lib/modules/6.11.8-300.fc41.x86_64/extra/zfs/zfs.ko
$ sudo /usr/src/kernels/$(uname -r)/scripts/sign-file sha256 /etc/pki/mok/LOCALMOK.priv /etc/pki/mok/LOCALMOK.der /lib/modules/$(uname -r)/extra/zfs/spl.ko
$ sudo /usr/src/kernels/$(uname -r)/scripts/sign-file sha256 /etc/pki/mok/LOCALMOK.priv /etc/pki/mok/LOCALMOK.der /lib/modules/$(uname -r)/extra/zfs/zfs.ko
Load the module and verify it is active:
$ sudo modprobe zfs
$ lsmod | grep zfs
zfs 6930432 0
spl 155648 1 zfs
Debian and Ubuntu
Make sure that the required packages are installed:
sudo apt install build-essential autoconf automake libtool gawk alien fakeroot dkms libblkid-dev uuid-dev libudev-dev libssl-dev zlib1g-dev libaio-dev libattr1-dev libelf-dev linux-headers-generic python3 python3-dev python3-setuptools python3-cffi libffi-dev python3-packaging debhelper-compat dh-python po-debconf python3-all-dev python3-sphinx libpam0g-dev
kmod
The key thing to know when building a kmod package is that a specific Linux kernel must be specified. At configure time the build system will make an educated guess as to which kernel you want to build against. However, if configure is unable to locate your kernel development headers, or you want to build against a different kernel, you must specify the exact path with the –with-linux and –with-linux-obj options.
To build RPM converted Debian packages:
$ cd zfs
$ ./configure --enable-systemd
$ make -j1 deb-utils deb-kmod
$ sudo apt-get install --fix-missing ./*.deb
Starting from openzfs-2.2 release, native Debian packages can be built as follows:
$ cd zfs
$ ./configure
$ make native-deb-utils native-deb-kmod
$ rm ../openzfs-zfs-dkms_*.deb
$ rm ../openzfs-zfs-dracut_*.deb # deb-based systems usually use initramfs
$ sudo apt-get install --fix-missing ../*.deb
Native Debian packages build with pre-configured paths for Debian and
Ubuntu. It’s best not to override the paths during configure.
KVERS, KSRC and KOBJ environment variables can be exported
to specify the kernel installed in non-default location.
DKMS
Building RPM converted deb-based DKMS and user packages can be done as follows:
$ cd zfs
$ ./configure --enable-systemd
$ make -j1 deb-utils deb-dkms
$ sudo apt-get install --fix-missing ./*.deb
Starting from openzfs-2.2 release, native deb-based DKMS and user packages can be built as follows:
$ sudo apt-get install dh-dkms
$ cd zfs
$ ./configure
$ make native-deb-utils
$ rm ../openzfs-zfs-dracut_*.deb # deb-based systems usually use initramfs
$ sudo apt-get install --fix-missing ../*.deb
Get the Source Code
Released Tarball
The released tarball contains the latest fully tested and released version of ZFS. This is the preferred source code location for use in production systems. If you want to use the official released tarballs, then use the following commands to fetch and prepare the source.
$ wget http://archive.zfsonlinux.org/downloads/zfsonlinux/zfs/zfs-x.y.z.tar.gz
$ tar -xzf zfs-x.y.z.tar.gz
Git Master Branch
The Git master branch contains the latest version of the software, and will probably contain fixes that, for some reason, weren’t included in the released tarball. This is the preferred source code location for developers who intend to modify ZFS. If you would like to use the git version, you can clone it from Github and prepare the source like this.
$ git clone https://github.com/zfsonlinux/zfs.git
$ cd zfs
$ ./autogen.sh
Once the source has been prepared you’ll need to decide what kind of packages you’re building and jump the to appropriate section above. Note that not all package types are supported for all platforms.