[Bug Report] AppImage broken on modern distros: dlopen(): error loading libfuse.so.2

Topic Type

Other

Detail of the issue

Hello folks at App5,

I just noticed that Neuron’s AppImage depends on libfuse2: many distributions now ship libfuse3 by default and may not install libfuse2 on a fresh system. This means that Neuron will not run out-of-the-box on fresh installs of recent mainstream distros such as Ubuntu, Fedora, Arch, Debian... That's why most AppImage maintainers are rebuilding images to bundle a libfuse3 runtime so they run without requiring host libfuse2.

That said, my personal suggestion would be to distribute Neuron via Flatpak, reason being:

Flatpak is slowly but steadily becoming the de-facto standard for distribuiting Apps on Linux, especially thanks ot the user-accessible tooling around it: discoverability, one-click install, updateability, easiness of restricting permissions...

On Flatpak these bases are well covered, we have user-accessible tools like: Bazaar, Flatseal, Warehouse ...

On AppImages we:

Get a binary
Verify the hash (we all do this, right?)
chmod +x ...
Double click
Hope for the best
(Optional side quest) Sometimes Gnome Nautilus strangely try to decompress it, later on you realize that you just forgot chmod, whoops 🤣🤣🤣

Just to make a comparison, on modern Linux distro:

1 click for an hypothetical Neuron Flatpak installation on most distro (3 steps if it's Ubuntu 🤣)
4 steps for an hypothetical Neuron libfuse3 installation (terminal still needed to check the hash)
The following steps for the current Neuron libfuse2 installation on a fresh Ubuntu Distrobox:

$ lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 24.04.1 LTS
Release:	24.04
Codename:	noble
$ wget https://github.com/nervosnetwork/neuron/releases/download/v0.202.1/Neuron-v0.202.1-x86_64.AppImage
...
$ sha256sum ~/Neuron-v0.202.1-x86_64.AppImage 
f3b5d50f33bf5d7ad15d67ef3f1024f668fe017d95a680c664abfff9f920dbdc  /var/home/user/Neuron-v0.202.1-x86_64.AppImage
$ chmod +x Neuron-v0.202.1-x86_64.AppImage
$ ./Neuron-v0.202.1-x86_64.AppImage
dlopen(): error loading libfuse.so.2

AppImages require FUSE to run. 
You might still be able to extract the contents of this AppImage 
if you run it with the --appimage-extract option. 
See https://github.com/AppImage/AppImageKit/wiki/FUSE 
for more information
$ sudo apt install libfuse2t64
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package libfuse2t64
$ sudo apt update
...
$ sudo apt upgrade
...
$ sudo apt install libfuse2t64
...
$ ./Neuron-v0.202.1-x86_64.AppImage
/tmp/.mount_NeuronCWaOt0/neuron-wallet: error while loading shared libraries: libnss3.so: cannot open shared object file: No such file or directory
$ sudo apt install libnss3
...
$ ./Neuron-v0.202.1-x86_64.AppImage
/tmp/.mount_NeuronMuTSYb/neuron-wallet: error while loading shared libraries: libasound.so.2: cannot open shared object file: No such file or directory
$ sudo apt install libasound2t64
...
$ ./Neuron-v0.202.1-x86_64.AppImage

Great Success!

Thank you for your hard work,
Phroi

bundled-ckb.log

bundled-ckb-light-mainnet.log

main.log

status.log

Thank you for your suggestion.
Neuron uses Electron-Builder for building and distribution. According to the Electron-Builder documentation, Electron-Builder currently does not support publishing applications to Flatpak repositories such as Flathub.
We will consider your suggestion once it is ready.

An external link is mentioned in the comment above. Please verify the link's safety before visiting.

@walker27

For anyone having to use a Ubuntu Distrobox to run Neuron and having issues with libfuse2, this is the full command to install the dependencies:

sudo apt update -y && sudo apt upgrade -y && sudo apt install libfuse2t64 libnss3 libasound2t64 -y

Back to us :

According to the Electron-Builder documentation, Electron-Builder currently does not support publishing applications to Flatpak repositories such as Flathub.

Additionally, electron-builder don't have a clear path for full Flatpak support.

The underlying issue still remains tho:

libfuse2 has been deemed End-Of-Life for 4 YEARS.
The build chain (electron-builder > Electron > Chromium) currently relies on the libfuse2 ABI
Chromium team has indicated they won't switch to libfuse3.

Result: for the foreseeable future, Neuron's AppImage remains dependent on the EOL libfuse2 ⚠️⚠️⚠️

@walker27 given Neuron is a security-focused CKB wallet, is this reasonable?

At the very least, please, could you try Neuron on the main Distros and document the commands needed to run Neuron?

Phroi

An external link is mentioned in the comment above. Please verify the link's safety before visiting.

https://issues.chromium.org/issues/410878548
[Feature Request]: Transition to libfuse3 so Electron apps still work in linux electron/electron#44131
Based on the discussion information in the two issues above, Chrome only depends on libfuse2 during the build runtime.
Furthermore, I was able to run the neuron source code on Ubuntu 24 (without libfuse2 installed), which may also prove the above point.
I also found a related issue on electron-builder, it currently appears to be more of an electron-builder packaging issue.
I will follow up on this issue.

An external link is mentioned in the comment above. Please verify the link's safety before visiting.

At the very least, please, could you try Neuron on the main Distros and document the commands needed to run Neuron?
ok, we will do more test on latest linux distro, create a issue as document

@walker27

Hey @walker27

we will do more test on latest linux distro, create a issue as document

That's something I look forward to as part of the CKB Community, Thank you so much!! 🥰

Chrome only depends on libfuse2 during the build runtime

Exactly, libfuse2 is a strange dependency: yesterday I found exactly electron/electron#44131, glad to see they are working around it in electron-userland/electron-builder#8686

BTW please, remember to tag me in the associated PRs, not that I'm qualified for reviewing code, but I'd like to keep an eye on how/if this issue is actually solved.

Love & Peace, Phroi

Mark this issue stale because no activity for 60 days

Issue is still unaddressed

Mark this issue stale because no activity for 60 days

@eval-exec

Hey @eval-exec!! Thank you for taking some time to address this issue!

Keep up the Great Work, Phroi

Mark this issue stale because no activity for 60 days

@eval-exec

@eval-exec still relevant: Neuron v0.204.1 still requires libfuse.so.2; the FUSE 3 fix in PR #3482 has not been merged or released.

(OFC I tried latest Neuron on my linux machine without libfuse.so.2 and it indeed still crashes)

@phroi

(OFC I tried latest Neuron on my linux machine without libfuse.so.2 and it indeed still crashes)

Friendly invite @phroi to try again.

Navigation Menu

Repository navigation

[Bug Report] AppImage broken on modern distros: `dlopen(): error loading libfuse.so.2` #3434

Topic Type

Detail of the issue

bundled-ckb.log

bundled-ckb-light-mainnet.log

main.log

status.log

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Bug Report] AppImage broken on modern distros: dlopen(): error loading libfuse.so.2 #3434

Description

Topic Type

Detail of the issue

bundled-ckb.log

bundled-ckb-light-mainnet.log

main.log

status.log

Activity

walker27 commented on Jan 12, 2026

github-actions commented on Jan 12, 2026

phroi commented on Jan 13, 2026

github-actions commented on Jan 13, 2026

walker27 commented on Jan 14, 2026

github-actions commented on Jan 14, 2026

walker27 commented on Jan 14, 2026

phroi commented on Jan 14, 2026

github-actions commented on Mar 16, 2026

phroi commented on Mar 16, 2026

github-actions commented on May 16, 2026

phroi commented on May 22, 2026

github-actions commented on Jul 21, 2026

phroi commented on Jul 21, 2026

phroi commented on Jul 21, 2026

eval-exec commented on Aug 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[Bug Report] AppImage broken on modern distros: `dlopen(): error loading libfuse.so.2` #3434