Skip to content

Commit 07a2e1d

Browse files
committed
docs: add FUSE troubleshooting for AppImage on modern Linux
modern distros (Ubuntu 22.04+, Debian 12+) ship FUSE 3 but AppImages require FUSE 2. document the fix (install libfuse2/libfuse2t64) and the --appimage-extract-and-run alternative.
1 parent 7686d89 commit 07a2e1d

File tree

1 file changed

+31
-0
lines changed

1 file changed

+31
-0
lines changed

README.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ When in doubt, pick one of package formats with built-in automatic update mechan
4646
- [Why am I missing the system tray menu on Linux?](#why-am-i-missing-the-system-tray-menu-on-linux)
4747
- [Why can't I install IPFS Desktop under Debian 11?](#why-cant-i-install-ipfs-desktop-under-debian-11)
4848
- [Why can't I start IPFS Desktop under Debian 10?](#why-cant-i-start-ipfs-desktop-under-debian-10)
49+
- [Why does the AppImage fail with a FUSE error?](#why-does-the-appimage-fail-with-a-fuse-error)
4950
- [`GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported`](#gtk-23-symbols-detected-using-gtk-23-and-gtk-4-in-the-same-process-is-not-supported)
5051
- [Where are my configuration and log files?](#where-are-my-configuration-and-log-files)
5152
- [IPFS Desktop configuration](#ipfs-desktop-configuration)
@@ -234,6 +235,36 @@ This is a known issue with Electron/Chrome and some hardened kernels. More detai
234235
$ ipfs-desktop --no-sandbox
235236
```
236237

238+
### Why does the AppImage fail with a FUSE error?
239+
240+
If you see this error when running the AppImage:
241+
242+
```
243+
dlopen(): error loading libfuse.so.2
244+
AppImages require FUSE to run.
245+
```
246+
247+
This happens because modern Linux distributions ship with FUSE 3, but AppImages currently require FUSE 2 (libfuse2). The two versions can coexist safely.
248+
249+
**Fix by distribution:**
250+
251+
| Distribution | Command |
252+
|--------------|---------|
253+
| Ubuntu 24.04+, Debian 13+ | `sudo apt install libfuse2t64` |
254+
| Ubuntu 22.04/23.x, Debian 12 | `sudo apt install libfuse2` |
255+
| Fedora | `sudo dnf install fuse-libs` |
256+
| Arch | `sudo pacman -S fuse2` |
257+
258+
**Alternative:** Run without FUSE using extraction mode:
259+
260+
```console
261+
./ipfs-desktop-*.AppImage --appimage-extract-and-run
262+
```
263+
264+
> **Note:** This is a known limitation of the AppImage runtime used by electron-builder. Future releases may include a static runtime that removes this dependency. See [AppImage/AppImageKit#1120](https://github.com/AppImage/AppImageKit/issues/1120) for upstream progress.
265+
266+
See [AppImage FUSE documentation](https://docs.appimage.org/user-guide/troubleshooting/fuse.html) for more details.
267+
237268
### `GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported`
238269

239270
See [ipfs-desktop#2952](https://github.com/ipfs/ipfs-desktop/issues/2952).

0 commit comments

Comments
 (0)