doc: Add `INSTALL.md` to Linux release tarballs #33451

hebasto commented at 7:32 PM on September 21, 2025: member

Closes #32097:

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

hebasto added the label Docs on Sep 21, 2025

DrahtBot commented at 7:32 PM on September 21, 2025: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33451.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	janb84, willcl-ark, w0xlt, sedited, achow101

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

hebasto added this to the milestone 30.0 on Sep 21, 2025

janb84 commented at 1:57 PM on September 25, 2025: contributor

ACK fc6d41d078656024cf9b3a8ef30b6cd2c79cfcf6

PR adds installation documentation for linux. The installation manual has an easy to copy section for installation of the QT dependencies.

Tested on clean Debian 13 install:

KDE already has all the dependencies installed, works out of the box. Installing the suggested dependencies results in 0 new installs.
XFCE is missing libxcb-cursor and the manual works as a charm in supplying that dependency.

Tested with binary version V30.0rc1

in doc/INSTALL_linux.md:19 in fc6d41d078

  14 | +The GUI executable, `bitcoin-qt`, is based on the Qt 6 framework and uses the `xcb` QPA (Qt Platform Abstraction) platform plugin
  15 | +to run on X11. Its runtime library [dependencies](https://doc.qt.io/archives/qt-6.7/linux-requirements.html) are as follows:
  16 | +- `libfontconfig`
  17 | +- `libfreetype`
  18 | +- `libxcb`
  19 | +- `libxcb-cursor`

fanquake commented at 3:20 PM on October 3, 2025:

libxcb-cursor can be removed now.

hebasto commented at 4:40 PM on October 4, 2025:

Removed.

hebasto force-pushed on Oct 4, 2025

hebasto commented at 4:40 PM on October 4, 2025: member

Feedback from @fanquake has been addressed.

janb84 commented at 8:26 AM on October 6, 2025: contributor

Feedback from @fanquake has been addressed.

I re-tested this but without libxcb-cursor I cannot start bitcoin-qt on Xcfe / Debian 13

./bitcoin-qt 
./bitcoin-qt: error while loading shared libraries: libxcb-cursor.so.0: cannot open shared object file: No such file or directory

edit: Tested this on a pre-compiled bin V30rc2.

willcl-ark commented at 8:29 AM on October 6, 2025: member

@janb84 you'll need to guix build a binary from a commit post #33434 (or for v30 with #33473 checked out)

janb84 commented at 9:16 AM on October 6, 2025: contributor

(re) ACK 0fe7d552ab213065b8d5807c3dd9f4e976717529

retested on Debian 13 / Xfce with recent guix build of master (a33bd767a37d) (No need for libxcb-cursor anymore)

achow101 commented at 8:09 PM on October 7, 2025: member

ACK 0fe7d552ab213065b8d5807c3dd9f4e976717529

55ee7f209c6cd5592a87472cacaf873e4a108f681465c238b66792a422306a15  guix-build-0fe7d552ab21/output/aarch64-linux-gnu/SHA256SUMS.part
eac376bc61d39740e37283df30c04ed330d1fe2ecc66ae2fb87e484c9f5589e1  guix-build-0fe7d552ab21/output/aarch64-linux-gnu/bitcoin-0fe7d552ab21-aarch64-linux-gnu-debug.tar.gz
7a31fb9bccf15dbb439f5a1600597188d8d97f4f0f9b94ccdf78bd1e90621421  guix-build-0fe7d552ab21/output/aarch64-linux-gnu/bitcoin-0fe7d552ab21-aarch64-linux-gnu.tar.gz
0ffbbdcaa274036ca21c20fed7ab6e638a824d2b474485fbab171a01c5da6066  guix-build-0fe7d552ab21/output/arm-linux-gnueabihf/SHA256SUMS.part
d7f86fb058ae62b788b6e555313bad68f44bb00210cf53433d1f0657560756ef  guix-build-0fe7d552ab21/output/arm-linux-gnueabihf/bitcoin-0fe7d552ab21-arm-linux-gnueabihf-debug.tar.gz
b00804cc7762bfa2cda2f689d04f86bcc6e8b2bb987a78404b8c8f38d5fe364e  guix-build-0fe7d552ab21/output/arm-linux-gnueabihf/bitcoin-0fe7d552ab21-arm-linux-gnueabihf.tar.gz
759612c7a3e8ab4b64e80b81a4c3d30ac5d54b6874a5d0bb802ce391df732ab2  guix-build-0fe7d552ab21/output/arm64-apple-darwin/SHA256SUMS.part
786f0d2f9818a7d8d9864208862fb53ae4564030b8331c10f5302538f45c4cd5  guix-build-0fe7d552ab21/output/arm64-apple-darwin/bitcoin-0fe7d552ab21-arm64-apple-darwin-codesigning.tar.gz
f20fa6b4da7a54d46f2047c92f52c6499dda860f3c418891a0ae39564ec78dfb  guix-build-0fe7d552ab21/output/arm64-apple-darwin/bitcoin-0fe7d552ab21-arm64-apple-darwin-unsigned.tar.gz
fcfe06a717da1ef1c7ad76f9b658a0ad7bf30f0d93e73a27226042259d662c30  guix-build-0fe7d552ab21/output/arm64-apple-darwin/bitcoin-0fe7d552ab21-arm64-apple-darwin-unsigned.zip
3bef7fec718e80e5884c563c98f38f8a36a089f130c60d019e36d669c8d4318c  guix-build-0fe7d552ab21/output/dist-archive/bitcoin-0fe7d552ab21.tar.gz
887855504cf7c36aeb04ab2844384fb15c26ddaf3928678b98a3ee5307575699  guix-build-0fe7d552ab21/output/powerpc64-linux-gnu/SHA256SUMS.part
0e6d33ed34549962cdf27df9bc6cfd3adc871bf469d6a29e1e3ede9800e7741d  guix-build-0fe7d552ab21/output/powerpc64-linux-gnu/bitcoin-0fe7d552ab21-powerpc64-linux-gnu-debug.tar.gz
2e3a91f09fe239f85a6bd86ead685a594ac4fc70f7a24f7c0b3ed5ed530ac6f7  guix-build-0fe7d552ab21/output/powerpc64-linux-gnu/bitcoin-0fe7d552ab21-powerpc64-linux-gnu.tar.gz
073a825d9fb32c5a4057777363fc6f04f092838943ea97c4189901742b661b2a  guix-build-0fe7d552ab21/output/riscv64-linux-gnu/SHA256SUMS.part
389314fbf4278edb7ce290b35db97e7b69394f9a1bdd7d6f37168ff0011382bb  guix-build-0fe7d552ab21/output/riscv64-linux-gnu/bitcoin-0fe7d552ab21-riscv64-linux-gnu-debug.tar.gz
673e69dbb2ac9a3c24944ec413735ad4ce4bab51af8517a99b1b571f8d17faef  guix-build-0fe7d552ab21/output/riscv64-linux-gnu/bitcoin-0fe7d552ab21-riscv64-linux-gnu.tar.gz
0049242872ac82dcc4efc69306804f501065f19d5b62fd9a24a4cbf7dcf67c68  guix-build-0fe7d552ab21/output/x86_64-apple-darwin/SHA256SUMS.part
60809178febc0f192a13f01281d9635ae6406ddc177c294e9e9405908308bb39  guix-build-0fe7d552ab21/output/x86_64-apple-darwin/bitcoin-0fe7d552ab21-x86_64-apple-darwin-codesigning.tar.gz
b4999771e3826a0e31696ad46409fd9907f912df03677b6da39cc57e2230c005  guix-build-0fe7d552ab21/output/x86_64-apple-darwin/bitcoin-0fe7d552ab21-x86_64-apple-darwin-unsigned.tar.gz
3ed7941101e6b307e34e08ee99f4b0d25d79e1825dd84e900073bf339d12f6ed  guix-build-0fe7d552ab21/output/x86_64-apple-darwin/bitcoin-0fe7d552ab21-x86_64-apple-darwin-unsigned.zip
20d51d8bfe9860f2d424f0ca4a737aba9a3fc92d11deab2cf8511c017baf9010  guix-build-0fe7d552ab21/output/x86_64-linux-gnu/SHA256SUMS.part
f3634f13cebc586f7da622231fa33c9c84fec1d445d4a36b37acb4eec7f61082  guix-build-0fe7d552ab21/output/x86_64-linux-gnu/bitcoin-0fe7d552ab21-x86_64-linux-gnu-debug.tar.gz
45cb7190ba16e204bd7f13b9e47b0db213e868e3e03d8f9ab45c75e66496b834  guix-build-0fe7d552ab21/output/x86_64-linux-gnu/bitcoin-0fe7d552ab21-x86_64-linux-gnu.tar.gz
fd14f20caa86aa52fb0240c9495e518e169eb9cba3a2700cae00b72cf0e980a2  guix-build-0fe7d552ab21/output/x86_64-w64-mingw32/SHA256SUMS.part
9d60ebe3d561bb46ba20f152104face77c63ec8c690c2d8b945cb70bdf6a9581  guix-build-0fe7d552ab21/output/x86_64-w64-mingw32/bitcoin-0fe7d552ab21-win64-codesigning.tar.gz
c6fb15b7e2607c9451dbffb4a9c256a451b9c1abaf04f5706ecaef995312a5bc  guix-build-0fe7d552ab21/output/x86_64-w64-mingw32/bitcoin-0fe7d552ab21-win64-debug.zip
fb868135b8019d8a5ff3837a9e49ed2210c859147f8d254bdd5258cf3f2a27a2  guix-build-0fe7d552ab21/output/x86_64-w64-mingw32/bitcoin-0fe7d552ab21-win64-setup-unsigned.exe
d285deabf9d152a690320fed89b7a5d38a2f237b4bdf4bf9697f7b7f750c28b0  guix-build-0fe7d552ab21/output/x86_64-w64-mingw32/bitcoin-0fe7d552ab21-win64-unsigned.zip

fanquake removed this from the milestone 30.0 on Oct 13, 2025

hebasto added this to the milestone 30.1 on Oct 16, 2025

in doc/INSTALL_linux.md:18 in 0fe7d552ab

  13 | +
  14 | +The GUI executable, `bitcoin-qt`, is based on the Qt 6 framework and uses the `xcb` QPA (Qt Platform Abstraction) platform plugin
  15 | +to run on X11. Its runtime library [dependencies](https://doc.qt.io/archives/qt-6.7/linux-requirements.html) are as follows:
  16 | +- `libfontconfig`
  17 | +- `libfreetype`
  18 | +- `libxcb`

fanquake commented at 12:02 PM on November 19, 2025:

xcb & xkb libs can be dropped.

hebasto commented at 11:34 AM on November 21, 2025:

Thanks! Dropped.

in doc/INSTALL_linux.md:15 in 0fe7d552ab

  10 | +
  11 | +GUI Runtime Requirements
  12 | +------------------------
  13 | +
  14 | +The GUI executable, `bitcoin-qt`, is based on the Qt 6 framework and uses the `xcb` QPA (Qt Platform Abstraction) platform plugin
  15 | +to run on X11. Its runtime library [dependencies](https://doc.qt.io/archives/qt-6.7/linux-requirements.html) are as follows:

fanquake commented at 12:03 PM on November 19, 2025:

I'm not sure we need to link to Qt docs here, given it's listing ~ 25 different things, of which only 2-3 are relevant to our binaries.

hebasto commented at 11:35 AM on November 21, 2025:

Thanks! Reworked.

fanquake commented at 12:08 PM on November 19, 2025: member

Should #29977 be closed, if we add these docs? Is 20.04 considered unsupported?

doc: Add `INSTALL.md` to Linux release tarballs d62f46eed4

hebasto force-pushed on Nov 21, 2025

hebasto commented at 11:34 AM on November 21, 2025: member

The recent feedback from @fanquake has been addressed.

hebasto commented at 11:37 AM on November 21, 2025: member

Should #29977 be closed, if we add these docs?

No need to wait for these docs. Static linking of xcb and friends should be sufficient.

Is 20.04 considered unsupported?

I think so.

fanquake removed this from the milestone 30.1 on Jan 2, 2026

sedited requested review from janb84 on Mar 5, 2026

janb84 commented at 10:11 AM on March 5, 2026: contributor

re ACK d62f46eed4be8998f4aa75e20bd0dca2e453313f

Tested on fresh Ubuntu 24.04 LTS and Bitcoin-core 30.2. for ubuntu no additional packages are needed to run bitcoin-qt, install document also mentions "to ensure" so that's fine.

Tested on fresh Debian 13 with xcfe and Bitcoin-core 30.2 also no additional packages are needed to launch bitcoin-qt

DrahtBot requested review from achow101 on Mar 5, 2026

willcl-ark commented at 10:43 AM on March 5, 2026: member

utACK d62f46eed4be8998f4aa75e20bd0dca2e453313f

I know we can't cover every system (don't worry, I'm not about to suggest Nix), but might we want to consider including Arch and, say, a BSD in these docs? It seems to me like including those would get us "most major Linux distro" coverage (and would not make unwieldly).

w0xlt commented at 5:48 PM on March 10, 2026: contributor

ACK d62f46eed4be8998f4aa75e20bd0dca2e453313f

sedited approved

sedited commented at 10:09 AM on March 11, 2026: contributor

ACK d62f46eed4be8998f4aa75e20bd0dca2e453313f

achow101 commented at 8:11 PM on March 13, 2026: member

ACK d62f46eed4be8998f4aa75e20bd0dca2e453313f

achow101 merged this on Mar 13, 2026

achow101 closed this on Mar 13, 2026

hebasto deleted the branch on Mar 13, 2026

fanquake commented at 12:13 AM on March 14, 2026: member

~0 Not really sure about this now, given the original motivation (X libs missing on major distros) doesn't actually apply.

I think it'd be better to have done something more like the windows readme. Having the repo readme + this file in the tarball, is an odd combination.