Building Pyjion from source is relatively involved process. Pyjion is a C++ project with a CMake build configuration. It requires libraries for Python and the .NET CLR.

Compiling from Source


  • CPython 3.10

  • CMake 3.2 +

  • .NET 6

At the command-line you can compile the project by using

> git clone --recurse-submodules
> cd pyjion
> python -m pip install -U
> python develop --build-type Debug

Pyjion uses a fork of scikit-build. This is because scikit-build still doesn’t have Visual Studio 2019 support.


Pyjion comes bundled with a devcontainer. Devcontainers are a specification used by VS Code and GitHub. They contain both instructions for building and a Dockerfile for Linux.

Devcontainers are the fastest way to get started on the Pyjion source code.

Github codespaces

GitHub codespaces can build and open the devcontainer if you select the option within github:


This requires access to the codespaces preview programme.

VS Code

When opening the directory, VS Code will detect the devcontainer and ask if you want to build and open the project in the dev container. This requires:

  • Docker

  • The Remote Containers extension

This dev container will build a Linux docker container with all of the prerequisites and compile the project ready for testing.

CMake Flags

Pyjion has CMake flags to add additional debug output in the compiled binary. You can set any flags on the command:

$ python develop --build-type Debug -DCOMPILER_DEBUG=ON

Full list of flags:




Emit debug messages in the compiler


Build the unit tests (on by default in Debug builds)


Enable Profile Generation (PGO)


Dump .NET JIT traces on compilation


Report .NET CLR faults


Dump IL and native sequence points after compiling


Dump graphviz instruction graphs during compilation


Because Pyjion is a complex project, it has a complex testing suite.

The tests are split into 4 stages:

  1. The C++ unit tests to verify isolated scenarios

  2. The Python tests to do integration testing and verify certain optimizations

  3. Performance benchmarks to measure performance improvements

  4. A test runner for the CPython regression suite

Catch2 Unit tests

The C++ unit test suite is around 1000 Python micro-functions to compile and test basic Python functionality.

You can run the unit tests binary from the build directory:

> ./unit_tests

test cases:  117 |  113 passed |  4 failed as expected
assertions: 6465 | 6367 passed | 98 failed as expected


There are some preconfigured benchmarks in Tests/benchmarks:

$ python Tests/benchmarks/

<function test_floats at 0x10621ff70> took 1.7167979199999999 min, 2.2481216809999998 max, 1.9089201766 mean without Pyjion
<function test_floats at 0x10621ff70> took 0.9969279479999997 min, 1.2294269269999987 max, 1.1075061115999998 mean with Pyjion
Pyjion is 41.98% faster
<function test_ints at 0x106892790> took 1.8965339189999995 min, 2.2599547509999987 max, 2.0514137473999994 mean without Pyjion
<function test_ints at 0x106892790> took 1.4789822159999986 min, 1.742200779000001 max, 1.6008296068000007 mean with Pyjion
Pyjion is 21.96% faster

This is not a comprehensive benchmark suite. There is the pyperformance benchmark suite available if you want to test, but keep in mind that some tests are still not compatible with Pyjion. See Known Limitations for more info.

Python test suite

The Python test suite is a Pytest project. It has custom Pytest hooks for:

  • Running each test 3 times

  • Preconfiguring Pyjion settings like the optimization level and profiling

$ pip install -r Tests/requirements_test.txt
$ python -m pytest Tests/ -v --opt-level 1

CPython Regression Test Suite

There are two custom test-runners for the CPython regression test suite.

  1. Smoke tests, a subset of the CPython regression tests

  2. The full test suite

The smoke-test runner has 2 additional flags. -o <level> to set the optimization level, and --pgc to enable PGC.

Here is an example of running the smoke tests:

$ python Tests/ -f Tests/python_smoke_tests.txt -o 0

The full test suite runner takes up to an hour to complete.

Here is an example of running the full test suite:

$ python -X dev -q Tests/ -f Tests/python_tests.txt -v

The test input file depends on the OS:

  • Tests/python_tests.txt for Linux

  • Tests/python_tests_macos11.txt for macOS

  • Tests/python_tests_win.txt for Windows