Build kaspad from source

Install Rust and build tools

Kaspad is written in Rust. rustup installs the compiler and cargo, its build tool.

Choose the default installation when asked:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The build also needs a C compiler, clang and the protobuf compiler. The rusty-kaspa README keeps the current list for each system. On Debian or Ubuntu:

sudo apt install -y build-essential git pkg-config libssl-dev clang libclang-dev protobuf-compiler libprotobuf-dev

On macOS:

xcode-select --install
brew install protobuf

Close and reopen the terminal, then check:

rustc --version
cargo --version

Get the code

Clone the official rusty-kaspa repository and switch to its stable branch, which the Kaspa developers recommend for running a node.

cd ~
git clone https://github.com/kaspanet/rusty-kaspa.git
cd rusty-kaspa
git checkout stable

kaspad/

The node

wallet/

The command-line wallet

rpc/

The RPC server and client

consensus/

Consensus rules

Build kaspad

The first build is the slow one: cargo downloads and compiles every dependency. Later builds only recompile what changed.

cargo build --release --bin kaspad

--release

Optimised: slower to build, faster to run

--bin kaspad

Builds only the node, not every program in the workspace

When it finishes, the program is here. Check it runs:

./target/release/kaspad --version

Run your build

Run it from where it was built to try it, or copy it somewhere on your PATH.

From the build folder (Ctrl+C stops it):

cd ~/rusty-kaspa
./target/release/kaspad --utxoindex --appdir=~/.kaspad

To run it from anywhere:

sudo cp target/release/kaspad /usr/local/bin/
kaspad --version

--utxoindex

Keeps an index for balance lookups (recommended)

--rpclisten=127.0.0.1:16110

Turns on RPC for this machine only

--appdir=~/.kaspad

Keeps the chain where the kaspad guides do

--loglevel=debug

More detail in the log

Keep it running

Optional: run it as a service so it starts with the machine and restarts if it stops.

Service setup is the same as for a downloaded kaspad; use your own build's path. See the macOS (launchd) or Linux (systemd) guides. The shortest version, for Linux:

[Unit]
Description=Kaspa node (kaspad, own build)
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/usr/local/bin/kaspad --utxoindex --appdir=/home/YOUR_USERNAME/.kaspad
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Replace YOUR_USERNAME, then:

sudo systemctl enable --now kaspad

Update your build

Pull the newest code and rebuild. With dependencies already compiled this usually takes 2 to 5 minutes.

# Stop the node first (Ctrl+C, or: sudo systemctl stop kaspad)
cd ~/rusty-kaspa
git pull origin stable
cargo build --release --bin kaspad

# If you copied it to /usr/local/bin, copy it again:
sudo cp target/release/kaspad /usr/local/bin/

# Start it again (./target/release/kaspad, or: sudo systemctl start kaspad)

To see what is new before pulling:

cd ~/rusty-kaspa
git fetch origin
git log HEAD..origin/stable --oneline

To build a particular release instead, check out its tag from the releases page, and git checkout stable to come back:

git checkout v<version>
cargo build --release --bin kaspad

Troubleshooting

The usual problems and what fixes them.