Skip to content

Getting Started

Jump to bottom
Benjamin Fleischer edited this page Apr 14, 2024 · 23 revisions

What is macFUSE?

macFUSE is a software package that brings support for FUSE file systems to macOS. FUSE file systems are regular applications that run in user space as opposed to kernel extensions. There are many third party products that rely on macFUSE to provide file system integration.

macFUSE enables developing file systems for many use cases, including but not limited to:

  • File system integrating of cloud storage services
  • Transparent encryption and decryption of files
  • Accessing volumes whose format is not supported by macOS
  • App-specific virtual volumes

How to install macFUSE?

Download the latest version of macFUSE from https://macfuse.io or https://github.com/macfuse/macfuse/releases, then double click the downloaded file and run the installer.

Please note: Although it is possible to install macFUSE using a package manager it is recommended to download the latest release from the macFUSE website instead. The macFUSE packages available through package managers are not managed by the macFUSE developers.

During the installation/update process you will be prompted to allow loading the macFUSE kernel extension. macFUSE enables developers to create file systems without having to write a single line of kernel code. The macFUSE kernel extension bridges the gap between user space file systems and the macOS kernel.

Enabling support for third party kernel extensions (Apple Silicon Macs)

Enabling support for third party kernel extensions is only needed when using macFUSE for the first time on an Apple Silicon Mac. In case you already enabled support for third party kernel extensions, continue with Allow the macFUSE kernel extension to load.

macOS 13 and later

On Apple Silicon Macs the following prompt will be displayed when trying to load a kernel extension for the first time.

Click on the "Open System Settings" button. This will open the Privacy & Security settings.

By default, third-party kernel extensions are disabled on Apple Silicon Macs. Click on the "Enable System Extensions…" button and enter your login password when prompted.

Click on "Shut Down". After your Mac has shut down, press and hold the Touch ID or power button of your Mac to start the Recovery environment and launch Startup Security Utility.




Select the macOS volume you want to update the security policies for. Usually there is only one volume. Then click on the "Security Policy…" button.


2

Select "Reduced Security" and enable "Allow user management of kernel extensions from identified developers". Then click on "OK", enter your login password when prompted and restart your Mac.

macOS 12 and earlier

On Apple Silicon Macs the following prompt will be displayed when trying to load a kernel extension for the first time.

Click on the "Open Security Preferences" button. This will open the Security & Privacy system preferences.

By default, third-party kernel extensions are disabled on Apple Silicon Macs. Click on the lock in the lower left corner of the window and enter your login password. Then click on the "Enable system extensions…" button.

Click on "Shut Down". After your Mac has shut down, press and hold the Touch ID or power button of your Mac to start the Recovery environment and launch Startup Security Utility.




Select the macOS volume you want to update the security policies for. Usually there is only one volume. Then click on the "Security Policy…" button.




Select "Reduced Security" and enable "Allow user management of kernel extensions from identified developers". Then click on "OK", enter your login password when prompted and restart your Mac.

Allow the macFUSE kernel extension to load (Apple Silicon and Intel Macs)

macOS 13 and later

On Apple Silicon and Intel Macs the following prompt will be displayed when trying to use macFUSE for the first time or after after installing a macFUSE update.

Click on "Open System Settings".

Click on the "Allow" button. You will be asked for your login password.

After restarting your Mac you can use macFUSE.

macOS 12 and earlier

On Apple Silicon and Intel Macs the following prompt will be displayed when trying to use macFUSE for the first time or after after installing a macFUSE update.

Click on "Open Security Preferences".

Click on the lock in the lower left corner of the window and enter your login password. Then click on the "Allow" button.

After restarting your Mac you can use macFUSE.

Troubleshooting Guide

  • Make sure to install all available updates for your macOS release and use the latest version of macFUSE.

  • In case there is no "Allow" button after following the above steps, trying to load the macFUSE kernel extension manually might help. Run the following command in Terminal:

    /usr/bin/sudo /usr/bin/kmutil load -p /Library/Filesystems/macfuse.fs/Contents/Extensions/14/macfuse.kext

    Replace the "14" in the above command with the major version number of the current macOS release you are running. You will need to enter your login password, when prompted, for this to work. Please note, your user account needs administrative permissions.

  • In case you are prompted to allow loading the macFUSE kernel extension again and again even though you clicked the "Allow" button and restarted your Mac when prompted to, you are running into a macOS bug. Starting with version 4.7.1, macFUSE contains a workaround for this issue.

    The macFUSE file system bundle contains several kernel extensions to support a wide range of macOS releases. In rare cases macOS picks the wrong extension. As a workaround you can strip the unused extensions from the macFUSE file system bundle by running the following command in Terminal.

    /bin/bash <(curl -Ls https://gist.github.com/bfleischer/46dde8226a47f218b4d4eb8a51c50136/raw)

    Please note, your user account needs administrative permissions and you will be prompted to enter your login password. Then try mounting the volume again and follow the instructions above.

  • Recent versions of macOS do not support loading third-party kernel extensions when booting from external volumes. There is no known workaround. This is a limitation of macOS, not macFUSE.

  • There are documented cases where third-party kernel extensions, that are not compatible with the currently running version of macOS, result in macOS refusing to load compatible third-party kernel extensions, including macFUSE. Prominent examples are (not conclusive):

    • Legacy BlackBerry USB Driver (/System/Library/Extensions/com.rim.driver.BlackBerryUSBDriverInt.kext)
    • Legacy versions of OpenZFS (Library/Extensions/spl.kext).

  • Report the issue to Apple. You can use Apple's Feedback Assistent app to do so. Use Spotlight to open it or navigate to /System/Library/CoreServices/Applications in Finder.

Notes

macFUSE does not require you to disable Gatekeeper or System Integrity Protection. All official macFUSE releases are digitally signed and approved by Apple's Notary Service. This means macFUSE is compatible with Gatekeeper and System Integrity Protection.

Clone this wiki locally