Linux download needs installation instructions

Sjors commented at 4:34 pm on March 19, 2025: member

Windows has an installer, macOS has the usual drag-me-to-application logic that most GUI users will be familiar with. But for Linux we just give people are bunch of binaries along with a README that lacks any installation instructions.

Worse, it turns out the binaries don’t work out of the box on a vanilla Ubuntu system. That’s not just because of Wayland, which we don’t support yet. Even on X11 it will miss certain libraries.

https://www.reddit.com/r/BitcoinBeginners/comments/14m8f9q/missing_required_library_to_run_core_on_ubuntu/

https://bitcoin.stackexchange.com/questions/122646/libxcb-xinerama0-library-required-by-bitcoin-qt

The easiest fix would be to point to https://bitcoin.org/en/full-node#other-linux-gui which at least gives some general instructions.

Better I think would be to add instructions for the most popular desktop distros.

I think it’s fine to assume that daemon users can figure it out for themselves.

hodlinator commented at 9:07 pm on March 19, 2025: contributor

https://bitcoin.stackexchange.com/questions/122646/libxcb-xinerama0-library-required-by-bitcoin-qt

(This seems to have led to #30061 with the same title).

Sjors commented at 9:22 am on March 20, 2025: member

That’s a useful reference. But the concern there is about security, i.e. the dependency on operating system libraries.

Here I’m just worried about the practically of installing. As linux desktop gets more user friendly, I expect fewer people to know how to figure out which libraries they’re missing and how to install them.

willcl-ark added the label Docs on Mar 20, 2025

fanquake referenced this in commit 8b9e99e996 on Aug 19, 2025

luke-jr referenced this in commit de3675ca8d on Aug 20, 2025

fanquake referenced this in commit 3d9314f383 on Aug 21, 2025

fanquake referenced this in commit a9701de0c9 on Aug 22, 2025

fanquake referenced this in commit d9532415da on Aug 22, 2025

maflcko commented at 10:15 am on August 26, 2025: member

I think this was fixed and can be closed?

fanquake commented at 5:31 pm on August 26, 2025: member

Yea I’m not sure. For master, the binaries still have a libxcb-cursor dependency, that may need to be installed. It’s not clear if #33238 will work for 29.x, so that will still have a libxcb-xinerama dependency, that may need to be installed, (same for 28.x). There’s a note about libxcb-cursor0 in build-unix, but that isn’t shipped with release binaries, or likely read by anyone who isn’t compiling from source, so it seems like any of this could benefit from additional documentation.

Thoughts @hebasto?

maflcko commented at 5:35 pm on August 26, 2025: member

There’s a note about libxcb-cursor0 in build-unix, but that isn’t shipped with release binaries, or likely read by anyone who isn’t compiling from source, so it seems like any of this could benefit from additional documentation.

I see, so it seems a bit related to https://github.com/bitcoin/bitcoin/issues/32565

fanquake added this to the milestone 30.0 on Sep 1, 2025

fanquake commented at 3:05 pm on September 1, 2025: member

Added this to 30.0, but this seems to need addressing for all release branches, in some way.

BenWestgate commented at 11:29 pm on September 9, 2025: contributor

If we added to the tarball:

0./share/applications/bitcoin-qt.desktop
1./share/icons/bitcoin128.png
2./share/mime/packages/x-scheme-handler-bitcoin.xml
3./share/doc/bitcoin-core/README.md
4./share/doc/bitcoin-core/bitcoin.conf

Then a local install can be performed by: tar xzf bitcoin-29.1-x86_64-linux-gnu.tar.gz --strip-components=1 --directory=$HOME/.local and a system wide install by: sudo tar xzf bitcoin-29.1-x86_64-linux-gnu.tar.gz --strip-components=1 --directory=/usr/local

We currently have two files in ./: README.md and bitcoin.conf which are in the wrong place for XDG Base Directory Specification that must be moved to enable the one line install.

bitcoin.conf either belongs in ./share/doc/bitcoin-core/ as documentation or perhaps more preferably generated at start-up and placed in the data_dir (default: ~/.bitcoin) similar to many other files.

Linux download needs installation instructions #32097