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:
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.11.4 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}