Skip to content

FAQ

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

FAQ

Besides the questions covered below, you may also find the Documentation and OpenZFS on OS X pages helpful.

General

What is OpenZFS on OS X?

See the OpenZFS on OS X page.

What does O3X mean?

O3X = OpenZFS on OS X.

What version of ZFS do you use?

OpenZFS. Pool version 5000. Filesystem version 5.

Pool version 5000 is pool version 28 plus support for feature flags. O3X supports pool version 5000 and pool versions less than or equal to 28. It does not support the closed-source Oracle Solaris ZFS pool versions 29 and up.

Can I set up a test pool using files instead of disks?

Yes. The example below uses regular files, though disk images can also be used.

cd /tmp
mkfile 10G aaa
mkfile 10G bbb
mkfile 10G ccc
sudo zpool create tank raidz /tmp/aaa /tmp/bbb /tmp/ccc

I compiled from source. How do I know that I am running what I compiled?

There are a couple of sysctl values you can read to determine which commit was compiled into your custom kexts. Assuming you used zfsadm to build, or ran the autoconf and configure steps before compiling, the following should work:

sysctl -a | grep kext
    spl.kext_version: 1.5.2-2_g115aa2f
    zfs.kext_version: 1.5.2-33_g9ac66a7

cd <path to source code>/zfs
git log -n 1
    commit 9ac66a71e53636eec04f4718b0b3870a18f07840
       Merge: 3326995 890ef86
       Author: zadmin <zadmin@jerry.local>
       Date:   Thu Jun 16 17:19:24 2016 +1000

       Merge branch 'master' of https://github.com/openzfsonosx/zfs

cd <path to source code>/spl
git log -n 2
     commit f1ff660a2f1fa340d451c2afa5f726f9bd3e609d
     Author: Brendon Humphrey <brendon.humphrey@mac.com>
     Date:   Sat Jun 18 20:25:09 2016 -0700
     ...
     commit 115aa2f05b6f843e0d39d4f6bf999602db120113
     Author: Jorgen Lundman <lundman@lundman.net>
     Date:   Thu May 12 09:48:31 2016 +0900
     ...

Match the short commit IDs from the sysctl output with the relevant commits in your source trees.

If you make a small local change and do not commit it, this technique will not work. One workaround is to commit your local changes in your clone so the build has a commit ID to report.

Best Practices

Do I have to use mirrors or raidz?

Have to? No. Should you? Almost always.

ZFS cannot repair errors it finds unless you have redundancy at the vdev level.

Can I set copies=2 instead of using mirrors or raidz?

copies=2 is a poor substitute for vdev-level redundancy. Two copies on a broken drive are still worthless.

That said, yes, you can set copies=2, but do so at your own risk.

Administration

How can I access the .zfs snapshot directories?

You need to set snapdir=visible and manually mount a snapshot.

sudo zfs set snapdir=visible tank/bob
sudo zfs mount tank/bob@yesterday
ls -l /tank/bob/.zfs/snapshot/yesterday/

You can list existing snapshots with:

zfs list -t snapshot

Is .zfs snapdir auto-mounting supported?

No. You must manually mount snapshots with zfs mount to see them in the snapdir.

I manually mounted my snapshot but still cannot see it in Finder. What gives?

Currently mounted snapshots are visible in Terminal, but not in Finder.

ls -l /tank/bob/.zfs/snapshot/yesterday/

Why does OS X Server not allow server storage to be on ZFS?

OS X Server has been written to only allow the server storage area to be on an HFS-formatted drive.

O3X includes a feature that causes ZFS datasets to identify themselves as HFS. This is enough for OS X Server to allow storage on a ZFS filesystem. HFS mimic is enabled by setting the com.apple.mimic_hfs property on a per-dataset basis.

As of OS X Server 5.x, it also appears that the Application Store Caching server can only store its cache on HFS. One workaround is to use an HFS-formatted ZVOL:

sudo zfs create -o volblocksize=1m -s -V 250g tank/cachingzvol

Interoperability

How do I create an O3X-compatible pool on another OpenZFS platform?

Only enable feature flags supported by O3X, as discussed here.

Can I import my ZEVO pools?

Yes. O3X can import pool version 28, which means it can import ZEVO pools.

Can I import my MacZFS pools?

Yes. O3X can import pool version 8, which means it can import MacZFS pools.

Do HFS-only applications such as Photos, iCloud Drive, and macOS Server work on ZFS?

Sometimes.

Apple writes some software to only work when stored on HFS. O3X includes a property that causes ZFS filesystems to identify themselves as HFS when enabled. That can help, but there is no guarantee the application will work perfectly, since HFS may have behavior the application depends on.

sudo zfs set com.apple.mimic_hfs=on <dataset>

Does Spotlight work?

Yes. Spotlight works on O3X 1.3.1 and later.

Can Time Machine backups be stored on ZFS?

Yes. It is possible to host a Time Machine backup within a sparse image on ZFS, or on an HFS-formatted ZVOL on ZFS. See Time Machine Backups.

Updating crypto to 2.0

If you are upgrading from 1.9.4 or earlier and use crypto, you may see mount returns -1. This is due to missing features such as userobjquota, groupobjquota, and projectquotas.

The pool will need zpool upgrade before it can be mounted. As with all pool upgrades, this means you cannot go back to 1.9.4 afterward.

Updating crypto to 2.0 from earlier 2.0 RC builds

Some early 2.0 RC releases calculated the MAC incorrectly, which may result in output like:

rpool/crypt:<0x0>

Running zpool scrub will clear the issue by recomputing the MAC.

Uninstalling on Big Sur and later

On Big Sur and later, macOS can sometimes hold on to kexts. The most reliable way to ensure the kext is no longer loaded is:

  1. Boot into Recovery Mode
  2. Launch Terminal
  3. Run:
kmutil trigger-panic-medic --volume-root /Volumes/<YourVolumeName>

For example: /Volumes/MacintoshHD

Then reboot normally.

trigger-panic-medic removes all third-party kexts, so you will need to re-approve any kexts you want to keep. Just make sure not to re-approve zfs.kext if you are uninstalling it.

After that, clean up the installed files:

sudo rm -rf /Library/Extensions/zfs.kext /usr/local/zfs/

Limitations

Can I use Finder permissions, also known as ACLs?

Not yet. There has been work in this area, but support is incomplete.

Can I boot my computer from O3X?

Yes. See ZFS on Boot.

So if I use O3X, that means I do not need backups, right?

Wrong. Very wrong.

Can Time Machine back up the contents of a ZFS volume?

No. At present, Time Machine excludes ZFS filesystems from the list of available backup targets.

How does auto-import work?

Auto-import on boot is handled by Launchd through:

  • /Library/LaunchDaemons/org.openzfsonosx.zpool-import-all.plist
  • /usr/local/libexec/zfs/launchd.d/zpool-import-all.sh

To temporarily stop auto-import, you can unload the plist or comment out the line:

"${ZPOOL}" import -a -d /var/run/disk/by-id

On newer versions, tested on 2.1.0, the script instead calls:

  • /Library/LaunchDaemons/org.openzfsonosx.zpool-import.plist

If you want to use physical drive naming by path, which is often more stable, edit that file and change:

<string>/var/run/disk/by-id</string>

to:

<string>/var/run/disk/by-path</string>

I cannot see my pools. What should I check?

First, make sure diskutil list shows the disks used in your pool. If not, you likely have a hardware or macOS issue to solve first.

Next, run:

zpool import

and, if needed:

zpool import -d /dev

This will make ZFS inspect disks on your system and list any pools it can find, along with their state. It will not list pools that are already imported. Use:

zpool list

to show imported pools.

To import a pool, run:

zpool import <poolname>

If you need more help, ask on the forum, IRC, or, in the case of panics, create an issue on GitHub.

Auto-import fails after Catalina

In System Preferences → Security & Privacy → Full Disk Access, allow bash.

The auto-import script uses bash. If you are using Lingon or a similar tool, switching the script to sh may also help.

Clone this wiki locally