docs/fuse.md
EXPERIMENTAL: FUSE support is functional but still evolving. Please report issues at kubo/issues.
Kubo can mount /ipfs, /ipns, and /mfs namespaces in your OS,
letting arbitrary apps access IPFS through standard filesystem operations.
The underlying FUSE implementation uses hanwen/go-fuse.
You will need to install and configure FUSE before you can mount IPFS.
Install fuse3 with your package manager:
# Debian / Ubuntu
sudo apt-get install fuse3
# Fedora
sudo dnf install fuse3
# Arch
sudo pacman -S fuse3
On some older Linux distributions, you may need to add yourself to the fuse group
for allow_other support (if no fuse group exists, you can skip this step):
sudo usermod -a -G fuse <username>
Restart your session for the change to apply.
Install macFUSE:
brew install --cask macfuse
After installation, open System Settings > Privacy & Security and allow the macFUSE kernel extension to load. A reboot may be required.
Kubo automatically sets volname, noapplexattr, and noappledouble mount options on macOS:
volname shows the filesystem name (ipfs, ipns, mfs) in Finder instead of the generic "macfuse Volume 0"noapplexattr stops Finder from probing Apple-private extended attributes on every file access, cutting FUSE traffic on network-backed mountsnoappledouble prevents macOS from creating ._ resource fork sidecar files, which would pollute the DAG with macOS-only metadata[!NOTE] macOS has known FUSE limitations (frequent STATFS calls, limited notification support) that may affect performance. See the
hanwen/go-fusemacOS notes for details.
Load the FUSE kernel module:
sudo kldload fusefs
To load automatically on boot:
echo 'fusefs_load="YES"' | sudo tee -a /boot/loader.conf
By default ipfs uses /ipfs, /ipns and /mfs directories for mounting. These can be
changed in config (see Mounts). You will have to create the directories
explicitly. Note that modifying root requires sudo permissions.
# make the directories
sudo mkdir /ipfs /ipns /mfs
# chown them so ipfs can use them without root permissions
sudo chown <username> /ipfs /ipns /mfs
Make sure no other IPFS daemon is already running, then start the daemon with FUSE mounts enabled:
ipfs daemon --mount
Or, if the daemon is already running:
ipfs mount
If you wish to allow other users to use the mount points, edit /etc/fuse.conf
to enable non-root users:
# /etc/fuse.conf - Configuration file for Filesystem in Userspace (FUSE)
# Set the maximum number of FUSE mounts allowed to non-root users.
# The default is 1000.
#mount_max = 1000
# Allow non-root users to specify the allow_other or allow_root mount options.
user_allow_other
Next set Mounts.FuseAllowOther config option to true:
ipfs config --json Mounts.FuseAllowOther true
ipfs daemon --mount
The /mfs mount exposes the MFS (Mutable File System) root as a FUSE filesystem.
This is the same virtual mutable filesystem as the one behind ipfs files commands
(see ipfs files --help), enabling manipulation of content-addressed data like regular files.
Standard tools like vim, rsync, and tar work on writable mounts (/mfs and /ipns).
Operations like fsync, ftruncate, chmod, touch, and rename-over-existing are all supported.
The CID for any file or directory is retrievable via the ipfs.cid
extended attribute:
$ getfattr -n ipfs.cid /mfs/hello.txt
# file: mfs/hello.txt
ipfs.cid="bafkreifjjcie6lypi6ny7amxnfftagclbuxndqonfipmb64f2km2devei4"
[!TIP] New IPFS nodes should run
ipfs config profile apply unixfs-v1-2025to use CIDv1 with modern defaults. Without this, files default to CIDv0 (base58Qm...hashes).
By default, IPFS does not persist POSIX mode or mtime, and most content on IPFS omits this metadata.
When mode or mtime is absent, FUSE mounts use sensible defaults:
/ipfs): files 0444, directories 0555/ipns, /mfs): files 0644, directories 0755When UnixFS metadata is present in the DAG (e.g. content added with mode/mtime preservation),
all three mounts show the stored values in stat responses regardless of config flags.
To persist mode and mtime when writing through FUSE, enable the opt-in config flags:
ipfs config --json Mounts.StoreMtime true
ipfs config --json Mounts.StoreMode true
These flags change the resulting CID even when file content is identical, because mode and mtime are stored in the UnixFS DAG node metadata.
See Mounts.StoreMtime and Mounts.StoreMode.
Permission denied or fusermount: user has no write access to mountpoint error in LinuxVerify that the config file can be read by your user:
sudo ls -l /etc/fuse.conf
-rw-r----- 1 root fuse 216 Jan 2 2013 /etc/fuse.conf
In most distributions, the group named fuse will be created during fuse
installation. You can check this with:
sudo grep -q fuse /etc/group && echo fuse_group_present || echo fuse_group_missing
If the group is present, just add your regular user to the fuse group:
sudo usermod -G fuse -a <username>
If the group didn't exist, create fuse group (add your regular user to it) and
set necessary permissions, for example:
sudo chgrp fuse /etc/fuse.conf
sudo chmod g+r /etc/fuse.conf
Note that the use of fuse group is optional and may depend on your operating
system. It is okay to use a different group as long as proper permissions are
set for user running ipfs mount command.
sudo umount /ipfs
sudo umount /ipns
sudo umount /mfs
Make sure your node's IPNS address has a directory published:
$ mkdir hello/; echo 'hello world' > hello/hello.txt
$ ipfs add -rQ ./hello/
bafybeidhkumeonuwkebh2i4fc7o7lguehauradvlk57gzake6ggjsy372a
$ ipfs name publish bafybeidhkumeonuwkebh2i4fc7o7lguehauradvlk57gzake6ggjsy372a
Set the IPFS_FUSE_DEBUG environment variable before starting the daemon to log all FUSE operations to stderr:
IPFS_FUSE_DEBUG=1 ipfs daemon --mount