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

This how-to provides step-by-step instructions for building Nitro locally using Docker on Debian, Ubuntu, or 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:

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

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.9.9 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 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 24

For Debian/Ubuntu

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

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 24
nvm use 24

Step 6. Configure Rust

Note that you may also need to use `rustup toolchain remove nightly...` to remove other Rust nightly toolchains that are installed

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup install 1.93.0
rustup default 1.93.0
rustup target add wasm32-unknown-unknown --toolchain 1.93.0
rustup target add wasm32-wasip1 --toolchain 1.93.0
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.25

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.25
gvm use go1.25 --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 version 1.2.3

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

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}

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

For Debian/Ubuntu

On this page