> For the complete documentation index, see [llms.txt](https://docs.qtum.info/qtum-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qtum.info/qtum-documentation/qtum-deployment/building-qtum-on-linux.md).

# Building Qtum on Linux

### Building Qtum Core on Ubuntu/Debian

#### Installing Dependencies

Install the required build dependencies:

bash

```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

```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

```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

```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

```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

```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

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

#### Build Without Wallet

For running a node without wallet functionality:

bash

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

#### View All Configuration Options

bash

```bash
./configure --help
```

### Running Qtum Core

After compilation, run the daemon:

bash

```bash
./src/qtumd -daemon
```

Or if built with the depends system:

bash

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

#### Create Configuration File

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

conf

```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

```bash
qtumd -daemon -logevents -txindex=1
```

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

bash

```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

```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

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

**Build Qtum**

bash

```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

```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

```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

```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

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

### Cross-Compilation

#### ARM (Raspberry Pi)

bash

```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

```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

```bash
make check
```

Run functional tests:

bash

```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

```bash
./autogen.sh
```

#### Out of Memory During Compilation

Use fewer parallel jobs:

bash

```bash
make -j2  # Use 2 jobs instead of all cores
```

Or disable parallel compilation:

bash

```bash
make
```

#### Berkeley DB Version Mismatch

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

bash

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

### Additional Resources

* **Build Documentation**: [build-unix.md](https://github.com/qtumproject/qtum/blob/master/doc/build-unix.md)
* **Dependencies Overview**: [dependencies.md](https://github.com/qtumproject/qtum/blob/master/doc/dependencies.md)
* **Depends System**: [depends/README.md](https://github.com/qtumproject/qtum/blob/master/depends/README.md)
* **Gitian Builds**: [Reproducible Builds Guide](https://github.com/qtumproject/qtum/blob/master/doc/gitian-building.md)
* **Release Notes**: [GitHub Releases](https://github.com/qtumproject/qtum/releases)

### Quick Reference

bash

```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
```