Building Qtum on Linux

Building Qtum Core on Ubuntu/Debian

Installing Dependencies

Install the required build dependencies:

bash

sudo apt update
sudo apt install build-essential libtool autotools-dev automake pkg-config \
  bsdmainutils python3 git cmake libboost-all-dev libgmp3-dev \
  libssl-dev libevent-dev

Note: CMake is required for building certain dependencies in the depends system.

Optional: GUI Dependencies

To build the Qt graphical interface (qtum-qt):

bash

sudo apt install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev \
  qttools5-dev-tools libprotobuf-dev protobuf-compiler qrencode

Optional: Wallet Dependencies

For legacy wallet support (Berkeley DB 4.8):

bash

# Install helper script will build BDB 4.8
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum
./contrib/install_db4.sh `pwd`
export BDB_PREFIX="$(pwd)/db4"

For descriptor wallet support, install sqlite3 (usually included by default on modern Ubuntu/Debian).

Compiling Qtum Core from Source

Method 1: Build with Depends System (Recommended)

This method builds all dependencies from source, ensuring compatibility:

bash

# Clone the repository
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

# Build dependencies
cd depends
make -j$(nproc)
cd ..

# Configure and build
./autogen.sh
./configure --prefix=$(pwd)/depends/x86_64-pc-linux-gnu
make -j$(nproc)

Binaries will be located in depends/x86_64-pc-linux-gnu/bin/.

Method 2: Build from Release Tarball

Download and build from a specific release:

bash

# Download latest release (replace version as needed)
wget https://github.com/qtumproject/qtum/archive/refs/tags/mainnet-v29.1.tar.gz
tar -xzf mainnet-v29.1.tar.gz
cd qtum-mainnet-v29.1

# Initialize submodules
git submodule update --init --recursive

# Build dependencies
make -C depends/ -j$(nproc)

# Configure with dependencies
./autogen.sh
./configure --prefix=$(pwd)/depends/x86_64-pc-linux-gnu
make -j$(nproc)

Binaries will be installed in depends/x86_64-pc-linux-gnu/bin/.

Method 3: System Dependencies (Advanced)

If you prefer using system libraries:

bash

git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

# Install Berkeley DB 4.8 for legacy wallet support
./contrib/install_db4.sh `pwd`
export BDB_PREFIX="$(pwd)/db4"

./autogen.sh
./configure \
  BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \
  BDB_CFLAGS="-I${BDB_PREFIX}/include"
make -j$(nproc)

Binaries will be in src/ directory.

Configuration Options

Build Without GUI

bash

./configure --without-gui --prefix=$(pwd)/depends/x86_64-pc-linux-gnu

Build Without Wallet

For running a node without wallet functionality:

bash

./configure --disable-wallet --prefix=$(pwd)/depends/x86_64-pc-linux-gnu

View All Configuration Options

bash

./configure --help

Running Qtum Core

After compilation, run the daemon:

bash

./src/qtumd -daemon

Or if built with the depends system:

bash

./depends/x86_64-pc-linux-gnu/bin/qtumd -daemon

Create Configuration File

Create ~/.qtum/qtum.conf for custom settings:

conf

# RPC credentials
rpcuser=your_username
rpcpassword=your_secure_password
server=1

# Enable smart contract event logging (required for QRC20 tokens)
logevents=1

# Run as daemon
daemon=1

# Allow RPC connections (default: localhost only)
rpcallowip=127.0.0.1

Enable QRC20 Token Support

To interact with QRC20 tokens, enable event logging and transaction indexing:

bash

qtumd -daemon -logevents -txindex=1

Important: If the blockchain is already synced, reindex to build the transaction index:

bash

qtumd -daemon -reindex -logevents -txindex=1

Note: Reindexing can take several hours depending on system performance.

Building on RHEL/CentOS/Fedora

CentOS 7

CentOS 7 requires additional setup due to older system packages:

Install Development Tools

bash

sudo yum update
sudo yum install -y epel-release centos-release-scl centos-release-scl-rh
sudo yum install -y devtoolset-7-gcc* tar unzip git wget patch make \
  autoconf automake libtool openssl-devel file which vim

Enable Modern GCC

bash

echo "source scl_source enable devtoolset-7" >> ~/.bashrc
source scl_source enable devtoolset-7

Build Qtum

bash

git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

# Build dependencies
make -C depends/ -j$(nproc)

# Configure and compile
./autogen.sh
./configure --prefix=$(pwd)/depends/x86_64-pc-linux-gnu
make -j$(nproc)

This produces a static build that can run on other Linux distributions.

Fedora

bash

sudo dnf install gcc-c++ libtool make autoconf automake openssl-devel \
  libevent-devel boost-devel libdb4-devel libdb4-cxx-devel python3 \
  gmp-devel git cmake

git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum
./autogen.sh
./configure
make -j$(nproc)

Building on Arch Linux

Example for a minimal node without wallet or GUI:

bash

sudo pacman -S --needed autoconf automake boost gcc git libevent \
  libtool make pkgconf python sqlite gmp cmake

git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum
./autogen.sh
./configure --disable-wallet --without-gui
make -j$(nproc)

Memory Optimization

C++ compilers are memory-intensive. On systems with limited RAM (< 1.5 GB), tune GCC to reduce memory usage:

bash

./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" \
  --prefix=$(pwd)/depends/x86_64-pc-linux-gnu

Alternatively, disable debug symbols:

bash

./configure CXXFLAGS="-O2" --prefix=$(pwd)/depends/x86_64-pc-linux-gnu

Cross-Compilation

ARM (Raspberry Pi)

bash

cd depends
make HOST=arm-linux-gnueabihf -j$(nproc)
cd ..
./autogen.sh
./configure --prefix=$(pwd)/depends/arm-linux-gnueabihf
make -j$(nproc)

ARM64 (aarch64)

bash

cd depends
make HOST=aarch64-linux-gnu -j$(nproc)
cd ..
./autogen.sh
./configure --prefix=$(pwd)/depends/aarch64-linux-gnu
make -j$(nproc)

Testing

Run the test suite (requires Python 3):

bash

make check

Run functional tests:

bash

./test/functional/test_runner.py

Troubleshooting

Build Fails Due to Missing Dependencies

Ensure all dependencies are installed. The autogen.sh script will indicate missing tools:

bash

./autogen.sh

Out of Memory During Compilation

Use fewer parallel jobs:

bash

make -j2  # Use 2 jobs instead of all cores

Or disable parallel compilation:

bash

make

Berkeley DB Version Mismatch

Always use Berkeley DB 4.8 for wallet compatibility with official releases:

bash

./contrib/install_db4.sh `pwd`
export BDB_PREFIX="$(pwd)/db4"

Additional Resources

• Build Documentation: build-unix.md

• Dependencies Overview: dependencies.md

• Depends System: depends/README.md

• Gitian Builds: Reproducible Builds Guide

• Release Notes: GitHub Releases

Quick Reference

bash

# View daemon help
./src/qtumd -help

# View RPC commands
./src/qtum-cli help

# View specific RPC command help
./src/qtum-cli help getblockchaininfo

# Start daemon
./src/qtumd -daemon

# Stop daemon
./src/qtum-cli stop

# Check sync status
./src/qtum-cli getblockchaininfo