Installing Dojo
Dojo's installation process was designed to be idiomatically consistent with its dependencies, Rust and Cairo. You can get up-and-running in just a few steps, and be building provable games in no time.
Quick Start
For existing Cairo developers, the fastest way to get started is with dojoup
:
# Install dojoup
curl -L https://install.dojoengine.org | bash
# Restart your terminal, then install Dojo
dojoup install
This will install all necessary dependencies and tools. Skip to Verification to test your installation.
Detailed Installation
System Requirements
Before installing Dojo, ensure your system meets these requirements:
- Operating System: macOS, Linux, or Windows with WSL2
- Memory: At least 4GB RAM (8GB recommended)
- Storage: 2GB free disk space for toolchains and dependencies
- Network: Stable internet connection for downloading binaries
- Dependencies:
curl
,jq
, andgit
(usually pre-installed on most systems)
Prerequisites
Before installing Dojo, you'll need these foundational tools:
1. Install Rust with rustup
Rust is required for Dojo's infrastructure tools (Katana and Torii).
Minimum version: 1.85.0
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
This installs Rust's executables, including the cargo
package manager, in the ~/.cargo
directory.
cargo --version
# Should output: cargo 1.85.0 (or later)
For more information, see the Rust installation guide.
2. Install Cairo with starkup
Dojo is written in Cairo, StarkWare's language for creating provable programs.
Minimum version: 2.10.1
curl --proto '=https' --tlsv1.2 -sSf https://sh.starkup.sh | sh
This installs Cairo's toolchain, including the scarb
package manager and build tool, in the ~/.asdf
directory.
Verify installation:Note:
asdf
does not automatically add itself to your path. Consider appending~/.asdf/shims
to your terminal's$PATH
variable to simplify development.
scarb --version
# Should output: scarb 2.10.1 (or later)
For more information, see the starkup documentation.
Installing Dojo
Option 1: Using dojoup
(Recommended)
dojoup
is the preferred way to install and manage Dojo installations:
Install dojoup
curl -L https://install.dojoengine.org | bash
This command installs dojoup
in the ~/.dojo
directory and adds it to your shell profile.
Important: You need to restart your terminal for the
dojoup
command to be available.
Install Dojo
In a new terminal window, run:
dojoup install
This installs katana
, torii
, and sozo
in the ~/.dojo
directory.
Advanced Usage
# Install a specific version
dojoup install 1.6.0
# Get help
dojoup --help
Option 2: Using asdf
You can alternatively use asdf
for more advanced version management:
Install asdf
Follow the asdf installation instructions for your platform, if not already installed.
Add the asdf-dojo plugin
asdf plugin add dojo https://github.com/dojoengine/asdf-dojo
Install Dojo
# Install the latest version
asdf install dojo latest
# Install a specific version
asdf install dojo 1.6.0
# List available versions
asdf list all dojo
Set the version
# Set version locally (in project directory)
asdf set dojo latest
# Set version globally (in user's home directory)
asdf set --home dojo latest
Verification
After installation, verify that all tools are working correctly:
Check Dojo Tools
# Check Sozo (CLI tool)
sozo --version
# Should output: sozo 1.6.0 (or later)
# Check Katana (sequencer)
katana --version
# Should output: katana 1.6.0 (or later)
# Check Torii (indexer)
torii --version
# Should output: torii 1.6.0 (or later)
Test Your Installation
Create a simple test project to verify everything works:
# Clone the dojo-starter repository
git clone https://github.com/dojoengine/dojo-starter
# Navigate to the project
cd dojo-starter
# Build the project
sozo build
# Test successful if no errors appear
Troubleshooting
Common Installation Issues
dojoup: command not found
Problem: After installing dojoup, the command is not found.
Solution:
- Restart your terminal completely
- If still not working, manually source the environment:
source ~/.dojo/env
- Check that
~/.dojo/bin
is in your PATH:echo $PATH | grep -o ~/.dojo
starkup
installation fails
Problem: starkup
fails to install or configure properly.
Solution:
- Ensure
asdf
is properly installed - Add
~/.asdf/shims
to your PATH:export PATH="$HOME/.asdf/shims:$PATH"
- Or, add it via your shell profile (
.bashrc
,.zshrc
, etc.)
Version compatibility issues
Problem: Incompatible versions between Rust, Cairo, or Dojo components.
Solution:
-
Check current versions:
cargo --version # Should be 1.85.0+ scarb --version # Should be 2.10.1+ sozo --version # Should be 1.6.0+
-
Update if needed:
rustup update # Update Rust asdf install scarb latest # Update Cairo/Scarb dojoup install # Update Dojo
Build failures in test project
Problem: sozo build
fails in the test project.
Solution:
-
Ensure all dependencies are installed
-
Try cleaning and rebuilding:
sozo clean && sozo build
-
Check for version mismatches between your installed tools
Getting Additional Help
If you continue to experience issues:
- Check the Dojo GitHub Issues for known problems
- Join our Discord for community support
- Review the Dojo Book for comprehensive documentation
Note: Version numbers in this guide are current as of the latest stable release. For the most current version numbers, check the Dojo releases page.
Code Editor Support
Visual Studio Code / Cursor
Install the Cairo 1.0 extension for:
- Syntax highlighting
- Error detection
- Auto-completion
- Code formatting
Getting Help
If you run into problems getting started with Dojo, join our Discord and ask for help.
Next Steps
With Dojo installed, you're ready to start building: