Setting up the environment


We recommend working inside a Python virtual environment, but you can also install the Cairo package directly. To create and enter the virtual environment, type:

python3.9 -m venv ~/cairo_venv
source ~/cairo_venv/bin/activate

Make sure the venv is activated – you should see (cairo_venv) in the command line prompt.

Make sure you can install the following pip packages: ecdsa, fastecdsa, sympy (using pip3 install ecdsa fastecdsa sympy). On Ubuntu, for example, you will have to first run:

sudo apt install -y libgmp3-dev

On Mac, you can use brew:

brew install gmp

Install the cairo-lang Python package using:

pip3 install cairo-lang

Alternatively, you can download the package ( from, and install it using:

pip3 install

Cairo was tested with python3.9. To make it work with python3.6, you will have to install contextvars:

pip3 install contextvars

Compiling and running a Cairo program

  1. Create a file, named test.cairo, with the following lines:

    func main() {
        [ap] = 1000, ap++;
        [ap] = 2000, ap++;
        [ap] = [ap - 2] + [ap - 1], ap++;
  2. Compile: (make sure all commands are executed in the virtual environment)

    cairo-compile test.cairo --output test_compiled.json
  3. Run:

    cairo-run \
      --program=test_compiled.json --print_output \
      --print_info --relocate_prints
  4. You can open the Cairo tracer by providing the --tracer flag to cairo-run. Then open it at http://localhost:8100/.

Visual Studio Code setup

Download the Cairo Visual Studio Code extension (cairo-0.13.0.vsix) from, and install it using:

code --install-extension cairo-0.13.0.vsix

Configure Visual Studio Code settings:

"editor.formatOnSave": true,
"editor.formatOnSaveTimeout": 1500

Note: You should start Visual Studio Code from the terminal running the virtual environment, by typing code. For instructions for macOS, see here.