Registry / devops / fusepy

fusepy

JSON →
library3.0.1pypypi✓ verified 86d ago

fusepy provides simple ctypes bindings for the FUSE (Filesystem in Userspace) library, allowing users to implement filesystems entirely in Python. The current version is 3.0.1, primarily focused on Python 3 compatibility and maintenance, with releases occurring infrequently as needed.

pip install fusepy
INSTALL
IMPORT
SIG · FUSEPY
F
fusepy
devopspythonv3.0.1
Install
2.4s avg
Import
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB
glibc
py 3.103.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)
Debug
Known issues
gotchaThe PyPI package is named `fusepy`, but the module you import in your Python code is `fuse` (e.g., `from fuse import FUSE`). Importing from `fusepy` directly will fail.
fix
Always use `from fuse import ...` for all classes and functions provided by this library.
affects: All versions
breakingStarting with version 3.0.0, fusepy officially dropped support for Python 2.x. It is now exclusively compatible with Python 3.
fix
Ensure your project is running on Python 3.x. For Python 2.x support, you would need to use an older fusepy version (e.g., 2.0.4), which is not recommended due to lack of maintenance.
affects: >=3.0.0
gotchafusepy is a binding to the FUSE system library, which must be installed on your operating system. Without it, `fusepy` cannot function.
fix
Install FUSE development libraries on your system. For Debian/Ubuntu: `sudo apt-get install libfuse-dev`. For macOS (with Homebrew): `brew install fuse-t`.
affects: All versions
gotchaFailing to explicitly unmount a FUSE filesystem can leave a stale mount point, potentially requiring a system reboot or manual cleanup of the mount directory.
fix
Always unmount your filesystem. If running in the foreground, `Ctrl+C` typically works. Otherwise, use `fusermount -u /path/to/mount` (Linux) or `umount /path/to/mount` (macOS/BSD).
affects: All versions
gotchaFUSE operations can be concurrent, meaning multiple threads might call your `Operations` class methods simultaneously. Your filesystem implementation must handle thread safety if you modify shared state.
fix
Implement proper locking mechanisms (e.g., `threading.Lock`) within your `Operations` class methods if they access or modify shared data structures.
affects: All versions
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.
fix
Ensure `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.
fix
Install `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.
fix
Add 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`.
fix
Implement 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.
fix
For 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.

Agent activity
2 hits · last 30 days
node
2
Resources