Installation

Starknet Foundry is easy to install on Linux, macOS and Windows. In this section, we will walk through the process of installing Starknet Foundry.

Contents

Requirements

📝 Note

Ensure all requirements are installed and follow the required minimum versions. Starknet Foundry will not run if not following these requirements.

To use Starknet Foundry, you need:

all installed and added to your PATH environment variable.

📝 Note

Universal-Sierra-Compiler will be automatically installed if you use asdf or snfoundryup. You can also create UNIVERSAL_SIERRA_COMPILER env var to make it visible for snforge.

Linux and MacOS

ℹ️ Info

If you already have installed Rust, Scarb and asdf simply run asdf plugin add starknet-foundry

Install Rust version >= 1.80.1

ℹ️ Info

snforge relies on Scarb's procedural macros to create snforge_scarb_plugin which is a part of snforge_std. This plugin is required for snforge test to work. Currently, procedural macros require Rust installation to function. This will be changed in the upcoming versions of Scarb.

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

To verify that correct Rust version was installed, run

rustc --version

and verify that version is >= 1.80.1

See Rust docs for more details.

Install asdf

Follow the instructions from asdf docs.

To verify that asdf was installed, run

asdf --version

Install Scarb version >= 2.7.0

First, add Scarb plugin to asdf

asdf plugin add scarb

Install Scarb

asdf install scarb latest

To verify that Scarb was installed, run

scarb --version

and verify that version is >= 2.7.0

Install Starknet Foundry

First, add Starknet Foundry plugin to asdf

asdf plugin add starknet-foundry

Install Starknet Foundry

asdf install starknet-foundry latest

To verify that Starknet Foundry was installed, run

snforge --version

or

sncast --version

Windows

Install Rust version >= 1.80.1

ℹ️ Info

snforge relies on Scarb's procedural macros to create snforge_scarb_plugin which is a part of snforge_std. This plugin is required for snforge test to work. Currently, procedural macros require Rust installation to function. This will be changed in the upcoming versions of Scarb.

Go to https://www.rust-lang.org/tools/install and follow the installation instructions.

To verify that correct Rust version was installed, run

rustc --version

and verify that version is >= 1.80.1

See Rust docs for more details.

Install Scarb version >= 2.7.0

Follow the instructions from Scarb docs.

  1. Download the release archive matching your CPU architecture from https://docs.swmansion.com/scarb/download.html#precompiled-packages.
  2. Extract it to a location where you would like to have Scarb installed. We recommend %LOCALAPPDATA%\Programs\scarb.
  3. From this directory, get the full path to scarb\bin and add it to PATH. See this article for instructions on Windows 10 and 11.

To verify that Scarb was installed, run

scarb --version

and verify that version is >= 2.7.0

Install Universal Sierra Compiler

  1. Download the release archive matching your CPU architecture from https://github.com/software-mansion/universal-sierra-compiler/releases/latest. Look for package with windows in the name e.g. universal-sierra-compiler-v2.3.0-x86_64-pc-windows-msvc.zip.
  2. Extract it to a location where you would like to have Starknet Foundry installed. We recommend %LOCALAPPDATA%\Programs\universal-sierra-compiler.
  3. From this directory, get the full path to universal-sierra-compiler\bin and add it to PATH. See this article for instructions on Windows 10 and 11.

To verify that Starknet Foundry was installed, run

universal-sierra-compiler --version

Install Starknet Foundry

  1. Download the release archive matching your CPU architecture from https://github.com/foundry-rs/starknet-foundry/releases/latest. Look for package with windows in the name e.g. starknet-foundry-v0.34.0-x86_64-pc-windows-msvc.zip.
  2. Extract it to a location where you would like to have Starknet Foundry installed. We recommend %LOCALAPPDATA%\Programs\snfoundry.
  3. From this directory, get the full path to snfoundry\bin and add it to PATH. See this article for instructions on Windows 10 and 11.

To verify that Starknet Foundry was installed, run

snforge --version

or

sncast --version

Common Errors

No Version Set (Linux and MacOS Only)

Users may encounter this error when trying to use snforge or sncast without setting a version:

No version is set for command snforge
Consider adding one of the following versions in your config file at $HOME/.tool_versions
starknet-foundry 0.32.0

This error indicates that Starknet Foundry version is unset. To resolve it, set the version globally using asdf:

asdf global starknet-foundry <version>

For additional information on asdf version management, see the asdf

Invalid Rust Version

When running any snforge command, error similar to this is displayed

Compiling snforge_scarb_plugin v0.34.0
error: package snforge_scarb_plugin v0.34.0 cannot be built because it requires rustc 1.80.1 or newer, while the currently active rustc version is 1.76.0

This indicates incorrect Rust version is installed or set.

Verify if rust version >= 1.80.1 is installed

rustc --version
1.80.1

To fix, follow the platform specific instructions:

Linux and MacOS

If the version is incorrect or the error persists, try changing the global version of Rust

rustup default stable

and local version of Rust

rustup override set stable

Windows

Follow Rust installation and ensure correct version of rust was added to PATH.

scarb test Isn’t Running snforge

By default, scarb test doesn't use snforge to run tests, and it needs to be configured. Make sure to include this section in Scarb.toml

[scripts]
test = "snforge test"

Universal-Sierra-Compiler update

If you would like to bump the USC manually (e.g. when the new Sierra version is released) you can do it by running:

Linux and MacOS

curl -L https://raw.githubusercontent.com/software-mansion/universal-sierra-compiler/master/scripts/install.sh | sh

Windows

Follow Universal Sierra Compiler installation for Windows.

How to build Starknet Foundry from source code

If you are unable to install Starknet Foundry using the instructions above, you can try building it from the source code as follows:

  1. Set up a development environment.
  2. Run cd starknet-foundry && cargo build --release. This will create a target directory.
  3. Move the target directory to the desired location (e.g. ~/.starknet-foundry).
  4. Add DESIRED_LOCATION/target/release/ to your PATH.