doc: add Linux GUI runtime instructions to doc/README.md #33197

pull Galoretka wants to merge 1 commits into bitcoin:master from Galoretka:docs/linux-gui-runtime-readme changing 1 files +7 −0

Galoretka commented at 2:28 pm on August 15, 2025: none
1. Add a “Linux GUI runtime libraries” subsection under the Unix section in doc/README.md.
2. List distro-specific Qt 6.5+ runtime packages already documented in doc/build-unix.md:
- Debian/Ubuntu: libxcb-cursor0 (optional qt6-wayland)
- Fedora: xcb-util-cursor (optional qt6-qtwayland)
- Alpine: xcb-util-cursor
1. Include a link to the “Other Linux” GUI guidance on bitcoin.org (https://bitcoin.org/en/full-node#other-linux-gui).
2. Rationale: doc/README.md ships in binary releases (see doc/files.md), so this helps Linux tarball users run the GUI out of the box. 5 Refs: #32097
DrahtBot added the label Docs on Aug 15, 2025
DrahtBot commented at 2:28 pm on August 15, 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/33197.

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.
willcl-ark commented at 2:31 pm on August 15, 2025: member

I think it’d be preferable not to link to docs on bitcoin.org from this file.
Galoretka commented at 7:44 pm on August 15, 2025: none

I think it’d be preferable not to link to docs on bitcoin.org from this file.

Yes sir

in doc/README.md:28 in 832e97bce0 outdated

20@@ -21,6 +21,32 @@ Unpack the files into a directory and run:
21 
22 The `bitcoin` command supports subcommands like `bitcoin gui`, `bitcoin node`, and `bitcoin rpc` exposing different functionality. Subcommands can be listed with `bitcoin help`.
23 
24+#### Linux GUI runtime libraries
25+
26+If you plan to run the GUI on Linux, your system may need Qt runtime packages provided by your distribution before launching `bin/bitcoin-qt`. Package names vary by distro. Examples:
27+
28+- Debian/Ubuntu (Qt 6.5+ runtime):

maflcko commented at 7:57 am on August 18, 2025:

the minimum required is 6.2? Why is this duplicated here at all?

Galoretka commented at 10:35 am on August 18, 2025:

the minimum required is 6.2? Why is this duplicated here at all?

really, removed copying

maflcko commented at 7:57 am on August 18, 2025: member

Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits
Galoretka force-pushed on Aug 18, 2025
Galoretka commented at 10:35 am on August 18, 2025: none

Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

squashed
docs: add linux GUI runtime readme 94090770a4

in doc/README.md:29 in 66fafff444 outdated

20@@ -21,6 +21,13 @@ Unpack the files into a directory and run:
21 
22 The `bitcoin` command supports subcommands like `bitcoin gui`, `bitcoin node`, and `bitcoin rpc` exposing different functionality. Subcommands can be listed with `bitcoin help`.
23 
24+#### Linux GUI install notes
25+
26+- Extract the release tarball and run `bin/bitcoin-qt` as described above.
27+- Depending on your distribution, additional system libraries may be required to run `bitcoin-qt`. On Debian/Ubuntu systems, you may need to install `libxcb-xinerama0` if you encounter a missing library error when launching the GUI:
28+  - `sudo apt install libxcb-xinerama0`
29+  - Background: `libxcb-xinerama0` has been reported as a required runtime dependency for some Ubuntu configurations when running the prebuilt binaries. See: `https://bitcoin.stackexchange.com/questions/122646/libxcb-xinerama0-library-required-by-bitcoin-qt` and related discussion in `https://github.com/bitcoin/bitcoin/issues/32097`.

maflcko commented at 10:46 am on August 18, 2025:

is the goal of this change to fix the issue?

fanquake commented at 10:40 am on August 21, 2025:

Opened #33217 to fix the issue.

Galoretka force-pushed on Aug 18, 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
fanquake commented at 10:32 am on August 22, 2025: member

The dependency on libxcb-xinerama0 has been removed in #33217 (which will also be backported to the 29.x branch) so I think pretty much all of the text being added here, is no-longer needed?
Galoretka commented at 5:49 pm on August 25, 2025: none

The dependency on libxcb-xinerama0 has been removed in #33217 (which will also be backported to the 29.x branch) so I think pretty much all of the text being added here, is no-longer needed?

so i should close pr?
maflcko commented at 10:16 am on August 26, 2025: member

Closing for now, as this was fixed already.
maflcko closed this on Aug 26, 2025

Contributors
Galoretka DrahtBot willcl-ark maflcko fanquake

Labels
Docs

doc: add Linux GUI runtime instructions to doc/README.md #33197

Code Coverage & Benchmarks

Reviews