Skip to content
The reference implementation of the Linux FUSE (Filesystem in Userspace) interface
Branch: master
Clone or download
jpandre and Nikratio Defined the (*ioctl)() commands as unsigned int (#381)
Instead of the Posix ioctl(2) command, Linux uses its own variant of ioctl()
in which the commands are requested as "unsigned long" and truncated to
32 bits by the fuse kernel module. Transmitting the commands to user space
file systems as "unsigned int" is a workaround for processing ioctl()
commands which do not fit into a signed int.
Latest commit a1bff7d Mar 11, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Add unprivileged option in `mount.fuse3` Oct 9, 2018
example Defined the (*ioctl)() commands as unsigned int (#381) Mar 11, 2019
include Defined the (*ioctl)() commands as unsigned int (#381) Mar 11, 2019
test Define ALLPERMS for musl libc systems. (#379) Mar 11, 2019
util Add HFS+ to filesystem whitelist (#347) Mar 9, 2019
.ackrc Added .ackrc Nov 24, 2018
.gitignore Added experimental support for building with Meson+Ninja Jan 12, 2017
.travis.yml Travis CI: Use Xenial instead of Trusty. Feb 27, 2019
AUTHORS Released 3.4.2 Mar 9, 2019
ChangeLog.rst Defined the (*ioctl)() commands as unsigned int (#381) Mar 11, 2019
GPL2.txt Clarified licensing terms. Oct 11, 2018
LGPL2.txt Clarified licensing terms. Oct 11, 2018
LICENSE Bump minimum Meson version Oct 16, 2018 Released 3.4.2 Mar 9, 2019
meson_options.txt Add build options for utils and examples Sep 28, 2018



FUSE (Filesystem in Userspace) is an interface for userspace programs to export a filesystem to the Linux kernel. The FUSE project consists of two components: the fuse kernel module (maintained in the regular kernel repositories) and the libfuse userspace library (maintained in this repository). libfuse provides the reference implementation for communicating with the FUSE kernel module.

A FUSE file system is typically implemented as a standalone application that links with libfuse. libfuse provides functions to mount the file system, unmount it, read requests from the kernel, and send responses back. libfuse offers two APIs: a "high-level", synchronous API, and a "low-level" asynchronous API. In both cases, incoming requests from the kernel are passed to the main program using callbacks. When using the high-level API, the callbacks may work with file names and paths instead of inodes, and processing of a request finishes when the callback function returns. When using the low-level API, the callbacks must work with inodes and responses must be sent explicitly using a separate set of API functions.

Supported Platforms

  • Linux (fully)
  • BSD (mostly/best-effort)
  • For OS-X, please use OSXFUSE


You can download libfuse from To build and install, we recommend to use Meson and Ninja. After extracting the libfuse tarball, create a (temporary) build directory and run Meson:

$ mkdir build; cd build
$ meson ..

Normally, the default build options will work fine. If you nevertheless want to adjust them, you can do so with the mesonconf command:

$ mesonconf # list options
$ mesonconf  -D disable-mtab=true # set an option

To build, test and install libfuse, you then use Ninja:

$ ninja
$ sudo python3 -m pytest test/
$ sudo ninja install

Running the tests requires the py.test Python module. Instead of running the tests as root, the majority of tests can also be run as a regular user if util/fusermount3 is made setuid root first:

$ sudo chown root:root util/fusermount3
$ sudo chmod 4755 util/fusermount3
$ python3 -m pytest test/

Security implications

The fusermount3 program is installed setuid root. This is done to allow normal users to mount their own filesystem implementations.

To limit the harm that malicious users can do this way, fusermount3 enforces the following limitations:

  • The user can only mount on a mountpoint for which he has write permission

  • The mountpoint must not be a sticky directory which isn't owned by the user (like /tmp usually is)

  • No other user (including root) can access the contents of the mounted filesystem (though this can be relaxed by allowing the use of the allow_other and allow_root mount options in /etc/fuse.conf)

If you intend to use the allow_other mount options, be aware that FUSE has an unresolved security bug: if the default_permissions mount option is not used, the results of the first permission check performed by the file system for a directory entry will be re-used for subsequent accesses as long as the inode of the accessed entry is present in the kernel cache - even if the permissions have since changed, and even if the subsequent access is made by a different user. This is of little concern if the filesystem is accessible only to the mounting user (which has full access to the filesystem anyway), but becomes a security issue when other users are allowed to access the filesystem (since they can exploit this to perform operations on the filesystem that they do not actually have permissions for).

This bug needs to be fixed in the Linux kernel and has been known since 2006 but unfortunately no fix has been applied yet. If you depend on correct permission handling for FUSE file systems, the only workaround is to use default_permissions (which does not currently support ACLs), or to completely disable caching of directory entry attributes.

Building your own filesystem

FUSE comes with several example file systems in the examples directory. For example, the passthrough examples mirror the contents of the root directory under the mountpoint. Start from there and adapt the code!

The documentation of the API functions and necessary callbacks is mostly contained in the files include/fuse.h (for the high-level API) and include/fuse_lowlevel.h (for the low-level API). An autogenerated html version of the API is available in the doc/html directory and at

Getting Help

If you need help, please ask on the mailing list (subscribe at

Please report any bugs on the GitHub issue tracker at

Professional Support

Professional support is offered via Rath Consulting.

You can’t perform that action at this time.