Building on Linux and Unix

Instructions for building Bitcoin Core on Linux and Unix systems

This guide explains how to build Bitcoin Core on Linux and Unix systems. For BSD-specific instructions, see the BSD build guide.

Basic Build Process

1. Configure the build

   Run CMake to configure the build system:

   cmake -B build
   

   To see all available configuration options:

   cmake -B build -LH
   
2. Build and install

   Compile Bitcoin Core and optionally install it:

   cmake --build build    # Append "-j N" for N parallel jobs
   cmake --install build  # Optional
   

Memory Requirements

C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of memory available when compiling Bitcoin Core.

On systems with less memory, compilation may fail or be extremely slow. Consider using the memory optimization options below.

Low Memory Optimization

If you have limited memory, you can tune GCC to conserve memory:

cmake -B build -DCMAKE_CXX_FLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"

You can also skip debugging information:

cmake -B build -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -g0"

Alternatively, use Clang instead of GCC (often less resource-hungry):

cmake -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang

Distribution-Specific Instructions

Ubuntu & Debian

1. Install build requirements

   Install the base build tools:

   sudo apt-get install build-essential cmake pkgconf python3
   

   For Debian “oldstable” or earlier Ubuntu LTS releases, you may need to install a newer compiler according to the dependencies documentation.

2. Install required dependencies

   Install the core dependencies:

   sudo apt-get install libevent-dev libboost-dev
   
3. Install wallet dependencies (optional)

   SQLite is required for wallet functionality:

   sudo apt install libsqlite3-dev
   

   To build without wallet support, use -DENABLE_WALLET=OFF during configuration.

4. Install IPC dependencies (optional)

   Cap’n Proto is needed for IPC functionality:

   sudo apt-get install libcapnp-dev capnproto
   

   To build without IPC, use -DENABLE_IPC=OFF during configuration.

5. Install ZMQ dependencies (optional)

   For ZMQ notification support:

   sudo apt-get install libzmq3-dev
   

   Enable with -DWITH_ZMQ=ON during configuration.

6. Install USDT dependencies (optional)

   For User-Space Statically Defined Tracing:

   sudo apt install systemtap-sdt-dev
   
7. Install GUI dependencies (optional)

   For the Qt-based GUI:

   sudo apt-get install qt6-base-dev qt6-tools-dev qt6-l10n-tools qt6-tools-dev-tools libgl-dev
   

   For Wayland support:

   sudo apt install qt6-wayland
   

   For QR code support in the GUI:

   sudo apt-get install libqrencode-dev
   

   Enable the GUI with -DBUILD_GUI=ON during configuration.

Fedora

1. Install build requirements

   sudo dnf install gcc-c++ cmake make python3
   
2. Install required dependencies

   sudo dnf install libevent-devel boost-devel
   
3. Install wallet dependencies (optional)

   sudo dnf install sqlite-devel
   
4. Install IPC dependencies (optional)

   sudo dnf install capnproto capnproto-devel
   
5. Install ZMQ dependencies (optional)

   sudo dnf install zeromq-devel
   
6. Install USDT dependencies (optional)

   sudo dnf install systemtap-sdt-devel
   
7. Install GUI dependencies (optional)

   For Qt GUI:

   sudo dnf install qt6-qtbase-devel qt6-qttools-devel
   

   For Wayland support:

   sudo dnf install qt6-qtwayland
   

   For QR codes:

   sudo dnf install qrencode-devel
   

Alpine

1. Install build requirements

   apk add build-base cmake linux-headers pkgconf python3
   
2. Install required dependencies

   apk add libevent-dev boost-dev
   
3. Install wallet dependencies (optional)

   apk add sqlite-dev
   
4. Install IPC dependencies (optional)

   apk add capnproto capnproto-dev
   
5. Install ZMQ dependencies (optional)

   apk add zeromq-dev
   
6. Install GUI dependencies (optional)

   apk add qt6-qtbase-dev qt6-qttools-dev
   

   For QR codes:

   apk add libqrencode-dev
   

User-Space Statically Defined Tracing (USDT) is not supported or tested on Alpine Linux.

Example: Arch Linux Build

This example shows the complete process to build Bitcoin Core on Arch Linux:

1. Install dependencies

   pacman --sync --needed capnproto cmake boost gcc git libevent make python sqlite
   
2. Clone the repository

   git clone https://github.com/bitcoin/bitcoin.git
   cd bitcoin/
   
3. Configure and build

   cmake -B build
   cmake --build build
   
4. Run tests

   ctest --test-dir build
   
5. Run Bitcoin Core

   ./build/bin/bitcoind
   ./build/bin/bitcoin help
   

Disable-Wallet Mode

When the intention is to only run a P2P node without a wallet, Bitcoin Core can be compiled in disable-wallet mode:

cmake -B build -DENABLE_WALLET=OFF

In this case there is no dependency on SQLite. Mining is also possible in disable-wallet mode using the getblocktemplate RPC call.

Alternative: Self-Compiled Dependencies

Instead of using your distribution’s packages, you can self-compile all dependencies using the depends system. See dependencies.md for more information.