cairo-vm: the Cairo virtual machine rewritten in Rust

What Cairo is, and why a VM sits under it

Cairo is described as the first production-grade platform for generating STARK proofs for general computation, and it is Turing-complete. It was created by Starkware as part of the Starknet ecosystem. The project description puts the point plainly: Cairo is a programming language for writing provable programs, where one party can prove to another that a certain computation was executed correctly without the need for that party to re-execute the same program. The virtual machine is the machine that runs it, and cairo-vm is that machine. The older implementation lived in the cairo-lang repository, was written in Python, and was used in production. This repository holds the newer Rust version, which the project says is faster and has safer and more expressive typing, and which is now in production as the primary Cairo VM, having replaced the Python one.

The dependencies, and which ones are actually optional

The required dependencies are Rust 1.85.0 or newer and Cargo. The optional ones are only necessary to run the original VM, compile Cairo programs and run tests, and they are make and uv, where uv is a modern Python package and environment manager made in Rust. Installing uv is a one-liner.

curl -LsSf https://astral.sh/uv/install.sh | sh

There is also an installation script, install.sh, which installs all the required and optional dependencies when run from the repository root. The separate dependency step is for compiling programs: you need the cairo-lang package installed, and running the make deps command creates a virtual environment with the required dependencies. You then activate that environment.

. cairo-vm-env/bin/activate

The distinction between the two groups is worth holding on to, because it determines what you actually have to install. If you are embedding the VM as a library or running pre-compiled programs, the Rust toolchain is the whole story.

Adding the VM to a Rust project

If you want to use cairo-vm from Rust code, the dependency goes into your project's Cargo.toml as a versioned entry.

cairo-vm = { version = '1.0.1'}

The version shown there is not the current one, and that discrepancy is worth a moment's attention. The workspace package version in the repository's Cargo.toml is 3.2.0, and the release history confirms it, with v3.2.0 on 2026-03-03, v3.1.0 on 2026-01-19 and v3.0.1 on 2025-12-23. So the project is on the 3.x line while the dependency snippet still names a 1.0.1 release, which means the example in the documentation is older than the current version. Anyone pinning should check the actual version against the repository rather than copying the line. The Cargo manifest is a workspace with members for the CLI, the VM itself, the hint processor, the hint accountant, the runner, the tracer and a hyper-threading example, and the default members are the CLI, the VM, the hint processor and the runner.

From zero to running a Cairo program

The project gives a single sequence that gets you from a clean machine to a running program, and it is worth following end to end because the ordering of the environment activation matters.

git clone https://github.com/starkware-libs/cairo-vm.git

cd cairo-vm

cargo build --release

. cairo-vm-env/bin/activate

cairo-compile cairo_programs/abs_value_array.cairo --output cairo_programs/abs_value_array_compiled.json

target/release/cairo-vm-cli cairo_programs/abs_value_array_compiled.json --layout all_cairo

The two-stage structure is the key. The cairo-compile step turns a .cairo source file into a compiled .json program, using the environment created when the dependencies were installed, and the cairo-vm-cli binary then executes that compiled program. The CLI binary itself is built from the cairo-vm-cli folder, with the sequence cd cairo-vm-cli; cargo build --release; cd .., after which the binary can be found in target/release/ under the name cairo-vm-cli. The --layout flag determines which builtins the program is allowed to use, and the documentation links to the builtins page for more on layouts.

Proof mode, and the flags that change what the run produces

The CLI takes a set of optional arguments that decide what comes out of a run, and the interesting one is --proof_mode, which runs the program in proof mode. Around it sit the output switches. --trace_file receives a file name and outputs the relocated trace into it, and --memory_file does the same for the relocated memory. --air_public_input outputs the AIR public inputs, and it can only be used if proof_mode is also enabled. --air_private_input outputs the AIR private inputs, and it can only be used if proof_mode, trace_file and memory_file are all enabled. --cairo_pie_output outputs the Cairo PIE, and it can only be used if proof_mode is not enabled. --print_output prints the program output, and --secure_run runs security checks after execution, which is enabled by default when not in proof_mode. The dependency chain between these flags is the design, because each stage of producing a proof needs the artefacts of the previous one.

Hints, the tracer, and the tools around the VM

Cairo programs cannot do everything themselves, and the mechanism for the rest is hints, which the project documents as its own usage section. The repository has dedicated crates for them, with cairo1-hint-processor and a hint_accountant in the workspace, plus a cairo-vm-tracer crate that is a separate member. The examples directory carries a custom_hint example and a hyper_threading one, and the Makefile has a dedicated hint-accountant target. The tracer also has its own binary, cairo-vm-tracer, alongside the CLI, the runner, and a fuzzer directory, which tells you the project treats input handling as an attack surface worth fuzzing. There is a bench/ directory, a compare_benchmarks target and a flamegraph target, and the Makefile has an extensive set of comparison targets that diff traces, memory, PIE and AIR inputs between two runs, which is how you find out whether a change altered anything.

Where cairo-vm is the wrong tool

Two boundaries make this the wrong choice. The first is purpose. A VM built so that execution can be proved is the right foundation for a blockchain that needs verifiable computation, and the wrong foundation for everything else, since the extra machinery buys you nothing if no proof is ever generated. The second is the toolchain, and it is heavier than a plain Rust crate because compiling Cairo programs and running the tests needs a Python environment created by make deps, along with make and uv, and because the Makefile itself has to build Cairo compiler binaries for Cairo 1 and Cairo 2, with separate targets for the STARKNET and Sierra compilers. The Makefile also notes that proof mode consumes so much memory with cairo-lang that the CI cannot execute two instances at once without being killed, which is why the build is marked not parallel. And the project says it is a faster and safer implementation rather than claiming feature parity with everything the Python version did.

Editorial conclusion

cairo-vm fits a Starknet developer who needs to run Cairo programs, generate proofs or trace execution and wants a VM that is faster than the Python one it replaced, and it fits anyone who wants to read how a proof-oriented VM handles hints, layouts and proof mode in Rust. It does not fit someone who wants to write Cairo from scratch with no interest in proving computation, since the whole design exists to make execution provable. It also does not fit a project without a Rust toolchain, since Rust 1.85.0 or newer and Cargo are required, and the optional path to compiling Cairo programs needs make and uv. Before you build, read the dependency notes, because the Python side is only needed to compile Cairo programs and run tests, not to use the VM as a library.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. starkware-libs/cairo-vm on GitHub