Install & Compatibility
Where this runs
tested against v3.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FUSE
✓ from fuse import FUSE
✗ from fusepy import FUSE
The package is `fusepy` but the installed module is `fuse`.
Operations
✓ from fuse import Operations
✗ from fusepy import Operations
The package is `fusepy` but the installed module is `fuse`.
FuseOSError
✓ from fuse import FuseOSError
✗ from fusepy import FuseOSError
The package is `fusepy` but the installed module is `fuse`.
This quickstart implements a basic, read-only filesystem with a single file '/hello.txt'. To run it, save the code and execute `python your_script.py /tmp/myfuse`. You'll need FUSE development libraries installed on your host system (e.g., `libfuse-dev` on Linux or `fuse-t` via Homebrew on macOS). Access the mounted filesystem with `ls /tmp/myfuse` or `cat /tmp/myfuse/hello.txt`. Press Ctrl+C to unmount, or use `fusermount -u /tmp/myfuse` (Linux) / `umount /tmp/myfuse` (macOS).
import os
import errno
import sys
from stat import S_IFDIR, S_IFREG
import time
from fuse import FUSE, FuseOSError, Operations
# Define a simple in-memory filesystem
class HelloFS(Operations):
def __init__(self):
self.files = {
'/': {
'st_mode': (S_IFDIR | 0o755), 'st_nlink': 2, 'st_size': 0,
'st_ctime': time.time(), 'st_mtime': time.time(), 'st_atime': time.time()
},
'/hello.txt': {
'st_mode': (S_IFREG | 0o444), 'st_nlink': 1, 'st_size': 13,
'st_ctime': time.time(), 'st_mtime': time.time(), 'st_atime': time.time(),
'content': b"Hello FUSE!\n"
}
}
def getattr(self, path, fh=None):
if path not in self.files:
raise FuseOSError(errno.ENOENT)
# fusepy expects stat-like attributes directly
attrs = self.files[path]
return {
'st_mode': attrs['st_mode'],
'st_nlink': attrs['st_nlink'],
'st_size': attrs['st_size'],
'st_ctime': attrs['st_ctime'],
'st_mtime': attrs['st_mtime'],
'st_atime': attrs['st_atime'],
}
def readdir(self, path, fh):
dirents = ['.', '..']
if path == '/':
dirents.extend([f.lstrip('/') for f in self.files if f != '/'])
for r in dirents:
yield r
def open(self, path, flags):
if path not in self.files or 'content' not in self.files[path]:
raise FuseOSError(errno.ENOENT)
return 0 # FUSE expects a file handle, 0 is often used for in-memory FS
def read(self, path, size, offset, fh):
if path not in self.files or 'content' not in self.files[path]:
raise FuseOSError(errno.ENOENT)
content = self.files[path]['content']
return content[offset:offset + size]
if __name__ == '__main__':
# !!! IMPORTANT: You MUST have FUSE development libraries installed on your OS !!!
# For Debian/Ubuntu: sudo apt-get install libfuse-dev
# For macOS with Homebrew: brew install fuse-t
# The mount point can be specified as a command-line argument.
# Example usage: python your_script.py /tmp/myfuse
# To unmount: `fusermount -u /tmp/myfuse` (Linux) or `umount /tmp/myfuse` (macOS/BSD)
mount_point = sys.argv[1] if len(sys.argv) > 1 else '/tmp/myfuse_example'
if not os.path.exists(mount_point):
os.makedirs(mount_point)
print(f"Mounting filesystem at {mount_point}. Press Ctrl+C to unmount.")
print(f"To interact: ls {mount_point}, cat {mount_point}/hello.txt")
# The FUSE daemon starts here.
# foreground=True keeps the process in the foreground, useful for debugging.
# ro=True makes the filesystem read-only.
FUSE(HelloFS(), mount_point, foreground=True, ro=True)
Errors
Common errors & fixes
ImportError: cannot import name FUSE
This error typically arises when there's a conflict between `fusepy` and the older `fuse-python` library, or when the `FUSE` class is incorrectly imported from the `fuse` module, or when `fusepy` is not properly installed or accessible in the Python environment.
fixEnsure `fusepy` is the only FUSE-related Python binding installed (`pip uninstall fuse-python fusepy` then `pip install fusepy`). Make sure the import statement is `from fuse import FUSE, Operations, FuseOSError` and that your environment's `PYTHONPATH` correctly points to the `fusepy` installation. If installing system-wide, ensure FUSE development headers are also installed (e.g., `sudo apt-get install libfuse-dev` on Debian/Ubuntu).
ModuleNotFoundError: No module named 'fuse'
This error occurs when the `fusepy` library (which is imported as `fuse`) is not installed or not found in the Python environment's path.
fixInstall `fusepy` using pip: `pip install fusepy`. If already installed, verify the installation path and ensure it's included in your `PYTHONPATH` or that your Python environment is correctly activated.
OSError: [Errno 1] Operation not permitted
This error often indicates that the user running the FUSE filesystem lacks the necessary permissions to perform a requested operation (e.g., mounting, writing to a file), or that the FUSE device itself isn't properly configured or accessible (e.g., `/dev/fuse` permissions). It can also happen if the `fuse` group is missing or the user is not part of it.
fixAdd your user to the `fuse` group (`sudo adduser $(whoami) fuse`) and log out/in. Ensure the mountpoint directory has correct permissions. Sometimes, running `modprobe fuse` or configuring `/etc/fuse.conf` can resolve device access issues. Avoid running with `sudo` unless absolutely necessary, and consider checking the underlying file system permissions for the paths your FUSE filesystem is interacting with.
OSError: [Errno 2] No such file or directory
This error typically means that a FUSE operation (like `getattr`, `open`, `readdir`) was called for a path that your filesystem implementation does not recognize or handle, causing it to return `errno.ENOENT`.
fixImplement all necessary filesystem operations (e.g., `getattr`, `readdir`, `open`) in your `fusepy.Operations` subclass to correctly handle all expected paths. Ensure that for paths that genuinely do not exist in your virtual filesystem, you explicitly `raise FuseOSError(errno.ENOENT)` to signal this to the kernel.
FuseOSError(EROFS)
This error, indicating a 'Read-only file system', often occurs when using `fusepy.Operations` as a base class and attempting write operations (like `create`, `write`, `unlink`) without providing a custom implementation. The default `Operations` class in `fusepy` implements many methods to return `EROFS`, assuming a read-only filesystem by default.
fixFor a read-write filesystem, explicitly override the relevant `fusepy.Operations` methods (e.g., `create`, `mkdir`, `unlink`, `rmdir`, `write`, `truncate`, `rename`) in your subclass with your desired read/write logic. If a specific operation is not supported, `raise FuseOSError(errno.ENOSYS)` instead of letting the default `EROFS` be returned.
Upgrade
Version history
3.0.1latest on PyPI · released Sep 17, 2018
Audit
Dependencies
No dependency data recorded yet.