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

1. 
   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

   3. Include a link to the “Other Linux” GUI guidance on bitcoin.org (https://bitcoin.org/en/full-node#other-linux-gui).
   4. 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
2. DrahtBot added the label Docs on Aug 15, 2025
3. 
   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.

4. 
   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.
5. 
   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

6. 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

7. 
   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
8. Galoretka force-pushed on Aug 18, 2025
9. 
   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

10. docs: add linux GUI runtime readme 94090770a4
11. 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?
12. Galoretka force-pushed on Aug 18, 2025

Contributors
Galoretka DrahtBot willcl-ark maflcko

Labels
Docs