FAQ
If the question you have is not answered here, try posting it to the macFUSE Google Group.
macFUSE is software that allows you to write arbitrary file systems as user space applications. You can think of it as a library for easily developing OS X file systems. Another crude way to look at this would be to think of macFUSE as something that makes OS X work like a microkernel for the purpose of writing/running file systems.
macFUSE has two major components: an in-kernel loadable file system and a user-space library (libfuse). The in-kernel file system is specific to OS X and is not based on Linux FUSE. (Some of its code is based on the FreeBSD implementation of FUSE.) The user-space library (libfuse), which provides the developer-visible FUSE API, has numerous OS X specific extensions and features.
The macFUSE software package is compatible with macOS 10.9 and later versions. It supports Intel and Apple Silicon Macs.
"macfuse-{version}.dmg" is the disk image containing the official distribution of fundamental macFUSE software you need to use other software built atop macFUSE. The core macFUSE software consists of the following components when installed on your Mac:
- macFUSE file system bundle
/Library/Filesystems/macfuse.fs - macFUSE Objective-C framework
/Library/Frameworks/macFUSE.framework - macFUSE C-based libraries
/usr/local/lib/libfuse*.dyliband headers/usr/local/include - macFUSE preference pane
/Library/PreferencePanes/macFUSE.prefPane
The macfuse.fs bundle in turn contains most of the core macFUSE software. Besides bundle metadata, its components include:
- macFUSE kernel extensions
macfuse.kext - macFUSE mount program
mount_macfuse - macFUSE kernel extension loader
load_macfuse
See question 2.3 for instructions on how to uninstall macFUSE.
You'll notice that there is a SHA256 checksum file and a PGP/GPG signature alongside the assets for each release. The .sha256 file is used to verify that the release files haven't been altered or corrupted. The .sha256.sig file is how you know the checksum file itself hasn't been altered, having been "signed" with the developer's private key.
In order to verify the signature of the checksum file, you'll need to obtain the developer's public key. Here are the basic steps, assuming you have gpg and curl available on your Mac, e.g., from Homebrew or MacPorts:
curl https://osxfuse.github.io/static/53C918C1A2818875.asc | gpg --import
gpg --verify macfuse*.sig
shasum -a 256 -c macfuse*.sha256
See #859 for more context.
1.4. I am experiencing serious problems (fill in details of serious problems here) right after I installed macFUSE. What can I do?
Circumstantial evidence such as "right after I installed 'macFUSE'" is unfortunately not enough to go on. To realize why macFUSE cannot cause the kind of problems people sometimes ascribe to it, you need to understand what macFUSE is, and just as importantly, what it is not.
macFUSE is not an application. It is not a background process. It is not something that launches automatically at boot time or any other time. It does not configure, reconfigure, or modify the normal working of OS X by itself. It does not alter settings of any OS X components besides placing its preference pane for System Preferences to use.
macFUSE is a bunch of libraries and headers along with a kernel extension. Developers use macFUSE APIs to write applications - just like how developers use Apple's Cocoa APIs to write applications. Just as Cocoa is not a user-tangible entity, macFUSE is not either.
The macFUSE kernel extension is not loaded automatically at boot time or any other time. It is dynamically loaded when a macFUSE-based application runs. Even when loaded, the kernel extension just occupies some memory - its code does not kick in until you actually mount a macFUSE-based file system.
The macFUSE updater runs only when explicitly asked by the user, say, by going to the macFUSE preference pane.
With this context, even if "it happened right after/only when you installed 'macFUSE'", macFUSE cannot do things such as the following:
- Affect the display
- Affect wireless networking
- Affect the computer's sleep or hibernate cycles
- Prevent the computer from booting
- Affect Finder settings, or any other program's settings
- Do anything to your computer's firmware
- Do anything to your computer's optical drive
- Cause HFS+ corruption or any other non-macFUSE-based file system's corruption
- ...
If you remain convinced that your woes are macFUSE's fault, please provide more information.
Note: macFUSE refers to the official version that can be downloaded from this web site. Everything here should generally apply to other repackagings/redistributionss of macFUSE, but they are not officially supported.
The recommended way to install macFUSE is to download the latest "macfuse-{version}.dmg" available from https://osxfuse.github.io/ and double-clicking on "Install macFUSE {version}".
The tools to keep macFUSE up-to-date (query the installed version, query for available updates, download and install updates, and so on) are built into macFUSE. Simply launch the "System Preferences" application and go to the macFUSE preference pane. It should tell you if there is and update and if so, will also let you download and install it.
Launch the "System Preferences" application and go to the macFUSE preference pane. Click on the "Remove macFUSE" button. This will uninstall all macFUSE components except the preference pane itself.
You can keep the macFUSE preference pane around should you decide to install macFUSE again in the future. If you do wish to remove it, you do it just like how you would remove any other non-Apple preference pane:
In System Preferences, control-click (right-click) on the macFUSE icon and you will see "Remove ..." as an action.
Note: If you had the "Show Beta Versions" button checked in the macFUSE preference pane, you will have a property list file remaining at: /Library/Preferences/com.github.osxfuse.plist. To remove it, you should un-check the button before you remove the preference pane as described above.
No, you are not required but highly recommended to do so.
2.5. I am using some software that needs an old/deprecated version of macFUSE. I do not see that version available on the web site. What to do?
Please do not use old/deprecated versions of macFUSE. The only "good" version of macFUSE is the latest one. Older versions become obsolete/unsupported as soon as a new release is out. It is an important goal of macFUSE to not break existing applications written atop it. Developers are encouraged to test their software against pre-release versions of macFUSE to help meet this goal.
-
NTFS-3G: For more information about NTFS-3G see NTFS-3G for Mac OS X.
-
SSHFS: For more information about SSHFS see SSHFS.
To be precise, by default macFUSE volumes show up as non-local volumes, which the Finder unfortunately treats the same as "servers". It is a good question as to why macFUSE normally tags its volumes as non-local. Some people think that in the case of disk-based file systems such as NTFS-3G, macFUSE must tag the volume as local.
For a VFS to be local on Mac OS X, you need a "real" disk device - a /dev/disk{number} style node. Such a real disk device node in macFUSE's case is problematic: at mount time, for a local volume, the kernel would
itself open the device node and pass it to macFUSE. In doing so, the kernel would make sure that the device is not currently in use (for one, to disallow multiple mounts of the same device). This happens before control passes to macFUSE and mounting can proceed. This would have been fine if the entire file system lived in the kernel, but in macFUSE's case, the user space file system program would also want to (exclusively) open the disk device.
Moreover, Disk Arbitration also gets involved in mounting and unmounting "local" volumes - this may be undesirable in some cases.
Technical reasons aside, there are arguments to justify that all macFUSE volumes are, in fact, "remote". (The semantics of "local" and "remote" are debatable, but that is another discussion.) As far as the macFUSE VFS is concerned, any and all volumes are remote in that their backing store lives across the kernel-user boundary, in a program that encapsulates backing store knowledge. macFUSE does not care about where the real backing store is - across the network, in the user program's memory, or on a "local" disk device.
One way to think of macFUSE user space file systems is indeed as "servers" - in the microkernel sense.
All this said, it is possible to tag a specific mount point as "local" at mount time. If you wish to do so, you can use the -o local mount-time option. This has caveats though: the Finder (and the operating system in general) may try to do things differently with local volumes. Some of these different things may not be what you want - for example, you may not want a .Trashes directory created on your volume. (It may not even be possible to create that directory in the case of certain file systems)
Check if the Finder preference for showing mounted servers on the Desktop is enabled. (Also see question 4.1 to understand why we are talking about "servers" here) You can either check if Finder > Preferences > General > Connected servers is checked, or you can use the defaults command from Terminal:
defaults read com.apple.finder ShowMountedServersOnDesktop
If the preference is unchecked, you can check it within the GUI or use defaults to set its value to 1:
defaults write com.apple.finder ShowMountedServersOnDesktop 1
Alternatively, you can use the -o local mount-time option to tag the volume being mounted as "local", in which case it would show up on the Desktop unless you have disabled "external disks" from showing up on the Desktop.
4.3. I mounted a macFUSE volume but I do not see a volume icon in the Finder's sidebar. I have looked at all relevant Finder preferences, but still nothing. What is happening?
The Finder by default will not show a macFUSE volume under the "DEVICES" section of the sidebar because the volume is not "local". The Finder will not show the volume under "SHARED" (even though it is "non-local") because it apparently thinks that non-local volumes must be of types such as AFP, NFS, SMB, and such. If you really want the volume to show up in the sidebar, you can use the -o local mount-time option. Also see questions 4.1 and 4.2.
To show all mounted volumes (including macFUSE volumes) in Finder click on Go > Computer in Finder's menu bar.
4.4. I tried to use file system (fill in file system here) with macFUSE and I am not happy because of (fill in reason here). What to do?
macFUSE is like a programming library. Individual file systems (like NTFS-3G, procfs, SSHFS, etc.) are programs written using that library. The quality and behavior of individual programs - of any kind - can vary wildly, and may or may not be an issue with the underlying library. If you have poor experience with an individual macFUSE file system, please determine (or help determine) if it is an issue specific to that file system or if it is a general issue with macFUSE. File systems are complex. macFUSE does simplify their implementation enormously, but nontrivial user space file systems can still be complex, and their performance/behavior can depend upon numerous factors besides macFUSE itself. When in doubt, feel free to post your questions on the macFUSE Google Group.
4.5. I am trying to access a macFUSE volume but I keep getting access/permission denied errors. I am doing this as root - what is going on? Is not everything allowed as root?
For several reasons, by default, macFUSE allows access to a volume only to the user who mounted the volume. All other users, including the superuser are denied access. You can change this behavior if you need to. Refer to the allow_other and allow_root mount-time options.
Yes, but by default, Spotlight processes running as root would not be able to access the volume, so you have to use certain mount-time options. See the answer to the previous question.
4.7. I tried to run gdb on an executable residing on a macFUSE file system but I got an "operation not permitted" error. What is going on?
gdb is a setgid executable on Mac OS X (see /usr/libexec/*gdb*). Therefore, under macFUSE's default mode of operation, it will not have access to macFUSE volumes. See the previous questions.
Just use the standard umount command in OS X. You do not need the Linux-specific fusermount with macFUSE.
4.9. All my file systems are showing up in the Finder as "macFUSE Volume {number} ({type})". What should I do?
Use the volname command-line mount-time option.
5.1. I am having problem (fill in problem here) compiling a FUSE file system in the macFUSE environment. What to do?
Besides any other file-system-specific compile- or configure-time options, you may need to have -D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE in CFLAGS unless it is already there (-D_DARWIN_USE_64_BIT_INODE is only needed when targeting Mac OS X 10.5). Try something like:
CFLAGS="-D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE" ./configure --prefix=/usr/local
macFUSE installs a fuse.pc file in /usr/local/lib/pkgconfig/. This, in conjunction with the pkg-config program, will automatically cause -D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE to be included in CFLAGS. If your particular installation of pkg-config (say, through MacPorts) does not look under /usr/local/lib/pkgconfig/ by default, you can set the environment variable PKG_CONFIG_PATH to /usr/local/lib/pkgconfig.
5.2. MacOS does not understand when I tells it that an extended attribute does not exist. What to do?
Read the manual! Unlike Linux, macOS defines ENOATTR to be different from ENODATA. Fix your code.
Since Linux removed the definition for ENOATTR, you will need to do this:
#ifndef ENOATTR
#define ENOATTR ENODATA
#endif