Skip to content

Install

Jump to bottom
Jorgen Lundman edited this page Apr 19, 2026 · 1 revision

Install

Installing the Official Release

Download the most recent DMG from the Downloads page.

Verify the checksums:

md5 OpenZFS_on_OS_X_*.dmg
shasum OpenZFS_on_OS_X_*.dmg
shasum -a 256 OpenZFS_on_OS_X_*.dmg

Open the .dmg file.

Read ReadMe.rtf.

Start the installer by opening OpenZFS_on_OS_X_x.y.z.pkg.

Follow the prompts.

Bash completion is also available. See Bash completion.

If you ever want to uninstall, follow the instructions for uninstalling a release version.

Installing from Source

Initial Installation from Source

For the newer port, the currently recommended ./configure line is:

./configure CPPFLAGS="-I/usr/local/opt/gettext/include -I/usr/local/opt/openssl@1.1/include" LDFLAGS="-L/usr/local/opt/gettext/lib/ -L/usr/local/opt/openssl@1.1/lib" CFLAGS="-g -O0" --sysconfdir=/etc --localstatedir=/var --prefix=/usr/local --sbindir=/usr/local/bin

Before doing anything else, please set your boot arguments.

On macOS Mojave (10.14), High Sierra (10.13), Sierra (10.12), El Capitan (10.11), Mavericks (10.9), and Mountain Lion (10.8):

sudo nvram boot-args="-v keepsyms=1"

On Yosemite (10.10):

sudo nvram boot-args="-v keepsyms=1 kext-dev-mode=1"

This takes effect the next time you reboot.

  • -v makes the boot screen verbose instead of just showing the Apple logo
  • keepsyms=1 makes panic reports more useful
  • kext-dev-mode=1 on Yosemite only allows loading custom unsigned kernel extensions

As of El Capitan, kext-dev-mode is obsolete and does nothing. If you are on Sierra or El Capitan, remove kext-dev-mode from your boot arguments to avoid confusion.

If you are a developer, you may also want debug=0x144 in your boot arguments, as described on the Development page.

Tips for getting into Recovery Mode, useful when developing on a VM:

sudo nvram "recovery-boot-mode=unused"
sudo reboot recovery

For Sierra (10.12) and El Capitan (10.11), you also need to boot into Recovery OS and run either:

csrutil disable

or:

csrutil enable --without kext

The second option allows you to load custom unsigned kernel extensions while leaving the rest of SIP in place.

Depending on your needs, other options you may want are --without fs, --without debug, --without dtrace, or --without nvram. Using all of them is equivalent to csrutil disable.

Starting with Catalina, you will probably also want to disable the reboot-to-load-kext behavior in Recovery:

spctl kext-consent disable

If you have any other implementation of ZFS installed, uninstall it and reboot before proceeding. Similarly, if you have installed the O3X installer version, follow the uninstallation directions before continuing.

Prerequisites

Note: Xcode 6.3 or later is required to build due to Broadwell CPU support requirements.

As of Xcode 8, if you are on 10.11 specifically, you also need to install the Command Line Tools:

xcode-select --install

To install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

If you already have Homebrew installed, run:

brew update && brew upgrade

Then check:

brew doctor

and address any issues that are not false positives.

If you have used Homebrew before, also run:

brew prune

Install the required packages:

brew install automake libtool gawk coreutils

autoconf will be installed automatically as a dependency of automake.

Set Up Your Workspace

Create two folders in your home directory:

mkdir -p ~/Developer ~/bin
chmod 700 ~/Developer ~/bin
chmod +a "group:everyone deny delete" ~/Developer ~/bin

Now adjust your PATH, unless it is already set appropriately.

If you are on Mavericks or above (10.9+), run:

echo 'export PATH=$HOME/bin:$PATH' >> ~/.bash_profile

If you are on Mountain Lion (10.8), run:

echo 'export PATH=$HOME/bin:/usr/local/bin:$PATH' >> ~/.bash_profile

Then reload your profile:

source ~/.bash_profile

Acquire the Sources and Build

To acquire the sources and build ZFS, use the zfsadm script:

cd ~/Developer/
git clone https://gist.github.com/7713854.git zfsadm-repo
cp zfsadm-repo/zfsadm ~/bin/

Now build OpenZFS on OS X:

zfsadm

This may take a few minutes depending on your hardware. Warnings during compilation are usually fine; errors are not.

Before using ZFS, you need to install it. If you are a developer and want to run it directly from the build tree, skip ahead.

cd ~/Developer/spl
sudo make install
cd ~/Developer/zfs
sudo make install

Check whether the kernel extensions loaded automatically:

kextstat | grep lundman

You should see something similar to:

137    1 0xffffff803f61a800 0x20c      0x20c      net.lundman.kernel.dependencies (10.0.0)
144    1 0xffffff7f82720000 0xd000     0xd000     net.lundman.spl (1.0.0) <137 7 5 4 3 1>
145    0 0xffffff7f8272d000 0x202000   0x202000   net.lundman.zfs (1.0.0) <144 13 7 5 4 3 1>

If not, make sure kextd is aware of them:

sudo touch /System/Library/Extensions
sudo killall -HUP kextd

Then check again:

kextstat | grep lundman

If they still have not loaded, you can load them manually:

cd /System/Library/Extensions
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

Try running:

zpool

to confirm everything is installed and configured properly.

You can go ahead and create your pools at this point.

Running ZFS from the Source Build

In the ZFS directory there is a script called load.sh which loads the two kext modules.

To run userland binaries from the source tree, use the provided cmd.sh script to set DYNDL_LIBRARY_PATH correctly.

Note that load.sh also starts tail -f /var/log/system.log for convenience.

$ sudo bash
# cd ~/Developer/zfs
# ./load.sh
kernel[0]: SPL: Loaded module v1.3.1-15_g4e2ff66 (DEBUG mode), (ncpu 4, memsize 4294967296, pages 1048576)
kernel[0]: ZFS: Loaded module v1.3.1-230_gb9658da, ZFS pool version 5000, ZFS filesystem version 5
# ./cmd.sh zpool import BOOM
# ./cmd.sh zpool list
NAME   SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
BOOM  39.8G   207M  39.5G         -     1%     0%  1.00x  ONLINE  -
# ./cmd.sh zpool export BOOM
Unmount successful for /Volumes/BOOM
# kextunload -b net.lundman.zfs
kernel[0]: ZFS: Unloaded module v1.3.1-230_gb9658da
# kextunload -b net.lundman.spl
kernel[0]: SPL: Released 524288 bytes from vmem_seg_arena
kernel[0]: SPL: Unloaded module. (os_mem_alloc: 0)

Upgrading a Source Install

When you want the latest commits from GitHub, here is a quick overview of what to run.

First make sure you have exported all of your pools.

zpool list

For every pool listed, run:

sudo zpool export <poolname>

Alternatively, export them all at once:

sudo zpool export -a

Make sure they exported successfully:

zpool status

It should say no pools available.

Get any zfsadm updates:

cd ~/Developer
[ -d zfsadm-repo/.git ] && (cd zfsadm-repo ; git pull)
[ ! -d zfsadm-repo/.git ] && git clone https://gist.github.com/7713854.git zfsadm-repo
cp zfsadm-repo/zfsadm ~/bin/

Now upgrade your ZFS installation:

cd ~/Developer

cd spl
make clean
cd ..

cd zfs
make clean
cd ..

zfsadm

# Assuming the build completed successfully,
# unload the kexts.

zfsadm -u

# Now install the upgrade.

cd spl
sudo make install
cd ..

cd zfs
sudo make install

# And verify they reloaded automatically

kextstat | grep lundman

# If not, make sure kextd is aware of them

sudo touch /Library/Extensions /System/Library/Extensions
sudo killall -HUP kextd

# and check again

kextstat | grep lundman

# if they still have not loaded automatically

cd /System/Library/Extensions
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

Uninstalling a Source Install

If you ever want to uninstall, follow the instructions for uninstalling a source install.

Using Without Actually Installing (Development)

This method is usually appropriate only for developers.

The procedure is the same as in Installing from Source, except that you never run make install. Instead, you load the kexts manually and execute the binaries directly from the source tree.

You can load the kexts manually by running:

zfsadm -k

By default, zfsadm -k copies spl.kext and zfs.kext from the build tree to /System/Library/Extensions, fixes ownership to root:wheel, and loads them directly from there.

If you prefer to use a different directory, use the -i option in zfsadm or edit zfsadm to hard-code a different path.

If you do not want to use zfsadm, you can do it manually. For example:

cd /tmp
sudo rm -rf o3x
sudo mkdir o3x

cd ~/Developer
sudo cp -R zfs/module/zfs/zfs.kext /tmp/o3x/
sudo cp -R spl/module/spl/spl.kext /tmp/o3x/

cd /tmp/o3x
sudo chown -R *
sudo kextload spl.kext
sudo kextload -d spl.kext zfs.kext

Once the kexts have been loaded, you can test the commands:

~/Developer/zfs/cmd.sh zfs

Migrating Old Pools (from MacZFS or ZEVO)

First export all of your pools and uninstall the other implementation. If you forgot to export your pools before uninstalling, that is OK. You will just need to use the -f option when importing into OpenZFS on OS X.

To find out the pool names, run pool discovery:

sudo zpool import

This shows which pools are available to import, but does not actually import them.

You can confirm that nothing has been imported yet with:

zpool status

Now import a pool by supplying the name or GUID shown during discovery:

sudo zpool import <poolname-or-guid>

If you forgot to export before migrating, use:

sudo zpool import -f <poolname-or-guid>

To see the current imported pool status, use:

zpool status

If all pools have been imported, then:

sudo zpool import

will return without any output.

Clone this wiki locally