Catalyst: a PennyLane JIT compiler whose frontend is planned to move upstream

The frontend is going into PennyLane, the compiler is staying behind

The roadmap section contains the single most consequential sentence in the readme, and it is easy to skim past because it is phrased as a plan. The PennyLane frontend will likely be upstreamed into PennyLane proper, which would give PennyLane native just-in-time functionality built in, and the Catalyst compiler and runtime will remain part of the Catalyst project. So the project is planning to give away its user-facing layer and keep the hard part. For anyone building on it now, that has two consequences. Code written against the frontend's decorator and its helper functions for control flow, gradients and mid-circuit measurement may need rewriting when the functionality lands upstream, since the packaging changes even if the behaviour does not. And the long-term shape is a PennyLane that compiles by default with Catalyst as the engine underneath, which is why the readme asks specifically for people interested in building additional frontends. If you are evaluating this for a long-lived internal tool, that migration is part of the cost.

An MLIR quantum dialect lowers to LLVM and QIR, and a binary comes out

The compilation path is described in three steps and it explains everything about the build. The core compiler is built on MLIR, the multi-level intermediate representation from the LLVM project, with a quantum dialect added on top to represent quantum instructions. That dialect gives a single high-level representation covering both the classical and the quantum parts of a program, which the readme says is what creates the optimisation advantage: a classical compiler cannot see through a quantum operation and a quantum compiler cannot see through a Python loop. Once optimised, the representation is lowered to LLVM plus QIR, the quantum intermediate representation from an alliance, and a machine binary is produced. Behind that sits the runtime, a C++ implementation with multiple-device support built on the same QIR, which executes the compiled program. The tree shows how much is vendored to make this work: directories for the LLVM project, for Enzyme, for StableHLO, and for the runtime, with a gitmodules file, so a source build is not a pip install with a compiler attached.

Every dependency bound exists because of a named bug

The requirements file is the most instructive document in the repository, because each constraint comes with a comment explaining which specific defect it works around. NumPy is held above 2.0.0 because a bug in that release's C interface blocked use of the stable ABI, and the comment notes the fix landed in 2.0.1. The bindings library is held between 2.9 and 2.13 because the underlying compiler project needs 2.9 or higher and a specific later version has a bug in its error handling. The Python bindings library has a floor of 2.12.0. The package installer has a floor because of a bug in editable installs against read-only system-wide site directories, which the comment notes cannot be expressed in the project file because by then it is too late. The build toolchain is CMake at 3.26 or newer plus a build accelerator, and the formatting and linting tools are pinned to exact or near-exact versions. None of this is stylistic caution. It is a project that upgrades deliberately and records why, which is exactly what you want in a dependency set that spans a compiler, a differential mathematics library and two binding layers.

Intel Macs stopped at 0.11.0, and the workaround is four pinned packages

Platform support is stated as Linux on two architectures and macOS on arm64, with pre-built binaries on the Python package index for Python 3.12 and later. The single install is one pip command. What makes this worth a section is the exception, which is documented with unusual precision. Support for macOS on the x86_64 architecture was dropped after 0.11.0, which the readme says includes Macs running Intel processors, and anyone who needs it is told to install a specific Catalyst version, a specific PennyLane version, a specific simulator version and a specific JAX version, with all four given as exact pins and one command each. That is a narrow, well documented escape hatch rather than an open ended breakage, and it tells you the shape of the compatibility surface: one package cannot move without the other three, so a team with a mixed Intel and arm64 fleet is pinning a large part of its numerical stack. Instructions for building from source are linked separately for anyone working on the runtime or compiler directly.

The device story today is a simulator and one plugin, hardware is listed as coming

The readme is careful to separate what runs now from what is planned. Support is stated for the high performance lightning simulators and for Amazon Braket devices through a plugin, with additional hardware support including quantum processing units described as to come. The runtime documentation holds the complete list of backends and the instruction set each supports, which is the right place to check before assuming a gate or operation is available, since the runtime implementations are per device. The roadmap for the runtime repeats the same order of work: more devices, including quantum hardware, then support for heterogeneous execution, and the text misspells the latter as hetereogeneous, which is a small clue that the section has not been recently rewritten. Two people-facing hooks exist for the runtime work, an invitation to get in touch if you want to connect a quantum device and a second invitation for anyone interested in additional frontends, which tells you where the project needs help most.

Differentiable end to end, and the frontend carries the control flow helpers

Differentiability is a stated design constraint rather than a feature bullet, and it is worth separating from the rest. The package is built to be end-to-end differentiable, which in a hybrid program means a gradient can pass through a circuit and through the classical code that drives it, including the optimisation loops the readme says can be compiled as a whole. The specific claim is that the entire quantum-classical workflow including any optimisation loops is compiled, not just the circuit body, which is the difference between accelerating a forward pass and accelerating a training step. The Python frontend is where that surfaces for users: it provides the decorator, plus Python functions for defining Catalyst-compatible control flow structures, for gradients, and for mid-circuit measurement. Control flow is called out as a feature in its own right, with advanced control flow that supports both quantum and classical instructions, and the compiler is described as having infrastructure for compiling quantum circuits that contain control flow rather than requiring you to unroll them first.

The Makefile is a build matrix, and ASAN breaks library loading in a documented way

The Makefile shows what a project with a vendored compiler has to coordinate. Build directories are named for the LLVM project, StableHLO, the dialect tree, the runtime, an external OQC component and Enzyme, and the targets are toggled by variables rather than edited: OpenQASM on by default, an OQD feature off, the test backend defaulting to the lightning qubit simulator, Braket tests off, address sanitizer off, a flaky test harness off, and an alternative dialect test suite on. There is also a platform branch that changes file copy flags, and a detailed comment about the address sanitizer, which is the kind of note that saves a day. The sanitizer intercepts the dynamic loading calls, so a library opened at runtime no longer resolves through the parent library's search path, which breaks loading a callback registry library and a BLAS provider used by the simulator. The stated workaround is setting the library path environment variable, and the comment notes that this is a development build issue only.

Editorial conclusion

This is worth trying if you already write hybrid quantum and classical code in PennyLane and your workload is dominated by Python interpretation overhead rather than by real device time, since decorating with the provided decorator is the entire adoption step and the compiler is built to stay differentiable end to end. It is the wrong tool if you need a quantum processing unit today, since hardware support is listed as forthcoming and the shipped device story is a simulator plus one plugin. It is also the wrong tool if you need Intel Macs, which were dropped after 0.11.0 and require pinning four packages to old versions. Before you commit, check three things: which frontend API you are writing against, because the roadmap says that frontend will be upstreamed into PennyLane and the surface you learn may move; whether your platform is on the supported list at all, since only Linux on two architectures and arm64 macOS are supported; and what the version numbers mean, because a quarterly development tag and a beta both exist alongside the stable releases, and the repository also carries a pinned dependency list where every upper bound is there because of a named upstream bug rather than a style preference.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes