Skip to content

installation.mdx

Latest commit

 

History

History
369 lines (244 loc) · 9.57 KB

installation.mdx

File metadata and controls

369 lines (244 loc) · 9.57 KB
Raw
title Dojo Installation Guide
description A comprehensive guide for installing a Dojo development environment across different platforms and use cases.

import { LinkCard } from "../components/LinkCard";

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.

:::warning Windows is not natively supported. We recommend WSL2 for Windows development. :::

Quick Start

For existing Cairo developers, the fastest way to get started is with our asdf installer. Simply run the following command in your terminal to install the Dojo toolchain.

curl -L https://install.dojoengine.org | bash

This script will install the asdf plugins for Sozo, Katana, and Torii, install their latest versions, and set them for global use. Skip to Verification to test your installation.

:::note This script requires asdf to be installed. See here for installation instructions. :::

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, and git (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.

Verify installation:

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.

:::note asdf does not automatically add itself to your PATH and must be configured manually. See more information about configuring asdf here. :::

Verify installation:

scarb --version
# Should output: scarb 2.10.1 (or later)

For more information, see the starkup documentation.

Installing Dojo

The Dojo framework consists of a Cairo framework and three Rust-based tools: katana, torii, and sozo.

:::note The Cairo framework is managed by Scarb as a compile-time dependency. See the Dojo configuration documentation for more info. :::

Installing with asdf

asdf is a popular version manager, supporting programmatic management of dependencies. asdf is the preferred way to install Dojo.

:::tip You can use our asdf installer to install the toolchain in a single command:

curl -L https://install.dojoengine.org | bash

:::

::::steps

Install asdf

Follow the asdf installation instructions for your platform.

Add the asdf plugins

asdf plugin add katana https://github.com/dojoengine/asdf-katana.git
asdf plugin add torii https://github.com/dojoengine/asdf-torii.git
asdf plugin add sozo https://github.com/dojoengine/asdf-sozo.git

Install the Dojo toolchain

# Install the latest version
asdf install {sozo,katana,torii} latest

# Install specific versions
asdf install {sozo,katana,torii} 1.6.0

# List available versions
asdf list all {sozo,katana,torii}

Set the version

# Set version locally (in project .tool-versions)
asdf set {sozo,katana,torii} latest

# Set version globally (in user home .tool-versions)
asdf set --home {sozo,katana,torii} latest

Using .tool-versions

asdf supports programmatic package management through the .tool-versions file.

# path/to/project/.tool-versions

scarb 2.12.2
sozo 1.7.1
katana 1.7.0
torii 1.8.3
starknet-foundry 0.43.1

Simply run asdf install in the project root to install all dependencies. If needed, asdf will download the correct version of all dependencies.

::::

Installing with dojoup

dojoup is an alternative way to install and manage Dojo installations. Dojoup is version-aware and will automatically install compatible versions of katana, torii, and sozo.

:::warning Dojoup is deprecated and will be removed in the future. Use the asdf installer instead. :::

::::steps

Install dojoup

curl -L https://raw.githubusercontent.com/dojoengine/dojo/main/dojoup/dojoup-install | bash

This command installs dojoup in the ~/.dojo directory and adds it to your shell profile.

:::info You need to restart your terminal for the dojoup command to be available. :::

Install the Dojo toolchain

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

::::

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

Claude Code Skills

Dojo provides official Claude Code skills that give Claude relevant context for working with models, systems, testing, deployment, and more. For an overview of available skills, see the Dojo Overview.

To install the skills, run the following in your terminal:

npx skills add dojoengine/book

Troubleshooting

Common Installation Issues

dojoup: command not found

Problem: After installing dojoup, the command is not found.

Solution:

  1. Restart your terminal completely
  2. If still not working, manually source the environment: source ~/.dojo/env
  3. 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:

  1. Ensure asdf is properly installed
  2. Add ~/.asdf/shims to your PATH: export PATH="$HOME/.asdf/shims:$PATH"
  3. Or, add it via your shell profile (.bashrc, .zshrc, etc.)

Version compatibility issues

Problem: Incompatible versions between Rust, Cairo, or Dojo components.

Solution:

  1. Check current versions:

    cargo --version    # Should be 1.85.0+
scarb --version    # Should be 2.10.1+
sozo --version     # Should be 1.6.0+

  2. 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:

  1. Ensure all dependencies are installed

  2. Try cleaning and rebuilding: sozo clean && sozo build

  3. Check for version mismatches between your installed tools

Getting Additional Help

If you continue to experience issues:

  1. Check the Dojo GitHub Issues for known problems
  2. Join our Discord for community support
  3. 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: