How to build Nitro locally (Debian, Ubuntu, MacOS)

Arbitrum Nitro is the software that powers all Arbitrum chains. This how-to shows how you can build a Docker image, or binaries, directly from Nitro's source code. If you want to run a node for one of the Arbitrum chains, however, it is recommended that you use the docker image available on DockerHub, as explained in How to run a full node.

This how-to assumes that you're running one of the following operating systems:

• Debian 11.7 (arm64)
• Ubuntu 22.04 (amd64)
• MacOS Sonoma 14.3.

Build a Docker image

Step 1. Configure Docker

For Debian/Ubuntu

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo service docker start

(Note that if you are running Ubuntu 22.04, you might get an Unable to locate package docker-buildx-plugin error. Try sudo apt install docker-buildx instead.)

For MacOS

Depending on whether your Mac has an Intel processor or Apple silicon, download the corresponding disk image from Docker, and move it into your Applications folder.

[Optional] Run docker from a different user

After installing docker, you might want to be able to run it with your current user instead of root. You can run the following commands to do so.

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

For troubleshooting, check Docker's section in their documentation

Step 2. Download the Nitro source code

git clone --branch v3.4.0 https://github.com/OffchainLabs/nitro.git
cd nitro
git submodule update --init --recursive --force

Step 3. Build the Nitro node Docker image

docker build . --tag nitro-node

That command will build a Docker image called nitro-node from the local source.

Build Nitro's binaries natively

If you want to build the node binaries natively, execute steps 1-3 of the Build a Docker image section and continue with the steps described here. Notice that even though we are building the binaries outside of Docker, it is still used to help build some WebAssembly components.

Step 4. Configure prerequisites

For Debian/Ubuntu

apt install git curl build-essential cmake npm golang clang make gotestsum wabt lld-13 python3
npm install --global yarn
ln -s /usr/bin/wasm-ld-13 /usr/local/bin/wasm-ld

For MacOS

Install Homebrew package manager and add it to your PATH environment variable:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo "export PATH=/opt/homebrew/bin:$PATH" >> ~/.zprofile && source ~/.zprofile

(replace ~/.zprofile with ~/.bash_profile if you use bash instead of zsh).

Install essentials:

brew install git curl make cmake npm go golangci-lint wabt llvm lld libusb gotestsum
npm install --global yarn
sudo mkdir -p /usr/local/bin
echo "export PATH=/opt/homebrew/opt/llvm/bin:$PATH" >> ~/.zprofile && source ~/.zprofile

Step 5. Configure node 18

For Debian/Ubuntu

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
source "$HOME/.bashrc"
nvm install 18
nvm use 18

For MacOS

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 18
nvm use 18

Step 6. Configure Rust 1.80.1

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup install 1.80.1
rustup default 1.80.1
rustup install nightly
rustup target add wasm32-unknown-unknown --toolchain 1.80.1
rustup target add wasm32-wasi --toolchain 1.80.1
rustup target add wasm32-unknown-unknown --toolchain nightly
rustup target add wasm32-wasi --toolchain nightly
rustup component add rust-src --toolchain nightly
cargo install cbindgen

Step 7. Install Bison 3.8.2

For Debian/Ubuntu

sudo apt-get install bison

For MacOS

brew install bison

Step 8. Configure Go 1.23

Install and configure Go

bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
source "$HOME/.gvm/scripts/gvm"
gvm install go1.23
gvm use go1.23 --default
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.54.2

If you use zsh, replace bash with zsh.

Install foundry

curl -L https://foundry.paradigm.xyz | bash
foundryup

Step 9. Check dependencies

./scripts/check-build.sh

If this script shows any errors, fix them before proceeding to the next step.

Step 10. Start build

make

Step 11. Produce binaries

make build

Warnings on MacOS

In MacOS with Apple Silicon, warnings like the following might appear but they will not hinder the compilation process.

ld: warning: object file was built for newer 'macOS' version (14.4) than being linked (14.0)

To silence these warnings, export the following environment variables before building Nitro.

export MACOSX_DEPLOYMENT_TARGET=$(sw_vers -productVersion)
export CGO_LDFLAGS=-Wl,-no_warn_duplicate_libraries

Step 12. Run your node

To run your node using the generated binaries, use the following command from the nitro folder, with your desired parameters

./target/bin/nitro <node parameters>

WASM module root error (v2.3.4 or later)

Since v2.3.4, the State Transition Function (STF) contains code that is not yet activated on the current mainnet and testnet chains. Because of that, you might receive the following error when connecting your built node to those chains:

ERROR[05-21|21:59:17.415] unable to find validator machine directory for the on-chain WASM module root err="stat {WASM_MODULE_ROOT}: no such file or directory"

Try add flag:

--validation.wasm.allowed-wasm-module-roots={WASM_MODULE_ROOT}