| 1 |
The JIT Compiler |
| 2 |
================ |
| 3 |
|
| 4 |
This version of CPython can be built with an experimental just-in-time compiler[^pep-744]. While most everything you already know about building and using CPython is unchanged, you will probably need to install a compatible version of LLVM first. |
| 5 |
|
| 6 |
Python 3.11 or newer is required to build the JIT. |
| 7 |
|
| 8 |
## Installing LLVM |
| 9 |
|
| 10 |
The JIT compiler does not require end users to install any third-party dependencies, but part of it must be *built* using LLVM[^why-llvm]. You are *not* required to build the rest of CPython using LLVM, or even the same version of LLVM (in fact, this is uncommon). |
| 11 |
|
| •12 |
LLVM version 19 is the officially supported version. You can modify if needed using the `LLVM_VERSION` env var during configure. Both `clang` and `llvm-readobj` need to be installed and discoverable (version suffixes, like `clang-19`, are okay). It's highly recommended that you also have `llvm-objdump` available, since this allows the build script to dump human-readable assembly for the generated code. |
| 13 |
|
| 14 |
It's easy to install all of the required tools: |
| 15 |
|
| 16 |
### Linux |
| 17 |
|
| 18 |
Install LLVM 19 on Ubuntu/Debian: |
| 19 |
|
| 20 |
```sh |
| 21 |
wget https://apt.llvm.org/llvm.sh |
| 22 |
chmod +x llvm.sh |
| 23 |
sudo ./llvm.sh 19 |
| 24 |
``` |
| 25 |
|
| 26 |
Install LLVM 19 on Fedora Linux 40 or newer: |
| 27 |
|
| 28 |
```sh |
| 29 |
sudo dnf install 'clang(major) = 19' 'llvm(major) = 19' |
| 30 |
``` |
| 31 |
|
| 32 |
### macOS |
| 33 |
|
| 34 |
Install LLVM 19 with [Homebrew](https://brew.sh): |
| 35 |
|
| 36 |
```sh |
| 37 |
brew install llvm@19 |
| 38 |
``` |
| 39 |
|
| 40 |
Homebrew won't add any of the tools to your `$PATH`. That's okay; the build script knows how to find them. |
| 41 |
|
| 42 |
### Windows |
| 43 |
|
| 44 |
LLVM is downloaded automatically (along with other external binary dependencies) by `PCbuild\build.bat`. |
| 45 |
|
| 46 |
Otherwise, you can install LLVM 19 [by searching for it on LLVM's GitHub releases page](https://github.com/llvm/llvm-project/releases?q=19), clicking on "Assets", downloading the appropriate Windows installer for your platform (likely the file ending with `-win64.exe`), and running it. **When installing, be sure to select the option labeled "Add LLVM to the system PATH".** |
| 47 |
|
| 48 |
Alternatively, you can use [chocolatey](https://chocolatey.org): |
| 49 |
|
| 50 |
```sh |
| 51 |
choco install llvm --version=19.1.0 |
| 52 |
``` |
| 53 |
|
| 54 |
|
| 55 |
## Building |
| 56 |
|
| 57 |
For `PCbuild`-based builds, pass the `--experimental-jit` option to `build.bat`. |
| 58 |
|
| 59 |
For all other builds, pass the `--enable-experimental-jit` option to `configure`. |
| 60 |
|
| 61 |
Otherwise, just configure and build as you normally would. Cross-compiling "just works", since the JIT is built for the host platform. |
| 62 |
|
| 63 |
The JIT can also be enabled or disabled using the `PYTHON_JIT` environment variable, even on builds where it is enabled or disabled by default. More details about configuring CPython with the JIT and optional values for `--enable-experimental-jit` can be found [here](https://docs.python.org/dev/using/configure.html#cmdoption-enable-experimental-jit). |
| 64 |
|
| 65 |
[^pep-744]: [PEP 744](https://peps.python.org/pep-0744/) |
| 66 |
|
| 67 |
[^why-llvm]: Clang is specifically needed because it's the only C compiler with support for guaranteed tail calls (`musttail`), which are required by CPython's continuation-passing-style approach to JIT compilation. Since LLVM also includes other functionalities we need (namely, object file parsing and disassembly), it's convenient to only support one toolchain at this time. |