Yao.jl: a Julia framework for quantum algorithm design, circuits and simulation

What problem Yao.jl solves, and who it is for

Yao.jl is a framework for quantum information research. The README names three audiences: quantum algorithm design, what it calls quantum software 2.0, and quantum computation education. That is a narrower claim than it first appears. Yao is not a cloud service, not a transpiler that targets a specific vendor's hardware, and not a gate-level language for writing circuits in a text file. It is a Julia library in which circuits are ordinary Julia values, so the same language you use for linear algebra, optimisation or machine learning also builds and manipulates the circuit.

The practical consequence: if your workflow already lives in Julia, Yao removes the boundary between the experiment and the maths around it. If your workflow lives in Python, Yao does not meet you there. The README points elsewhere for two things people often assume are included. CUDA support is not in this repository; it is in CuYao.jl. Tensor-network based simulation is in YaoToEinsum.jl. Yao itself is the core, and the surrounding capability is split across sibling packages.

How circuits are built: blocks, chains and registers

The mechanism visible in the README is the quantum block. A block is a composable description of an operation on a register of qubits, and the README's own example composes one in a few lines: a controlled phase rotation defined with control and shift, a chain that places a Hadamard on one wire and the rotations on the rest, and a function that chains those together into a quantum Fourier transform. The whole QFT is three lines of Julia.

That is the design idea. Small block constructors (put, control, chain, shift) are combined by ordinary function composition, and the result is itself a block that can be simulated, drawn or transformed. The Makefile confirms the layering behind this: lib/YaoAPI, lib/YaoArrayRegister, lib/YaoBlocks, lib/YaoSym, lib/YaoPlots and lib/YaoToEinsum are separate packages developed against each other in dependency order. YaoAPI sits at the bottom, YaoArrayRegister and YaoBlocks build on it, and YaoSym, YaoPlots and YaoToEinsum build on those. So the abstraction boundary in the code matches the abstraction boundary in the user's head: an API layer, a state/register layer, and a block layer.

The README does not document the simulation strategy in detail, nor does it state complexity or memory limits. Anyone choosing Yao for a problem of a given qubit count should read the stable documentation rather than infer scaling from the README.

Installing Yao.jl and running the QFT example

Yao is a registered Julia package. The README gives one installation path: open the Julia REPL, press the ] key to enter package mode, and add the package. The stable release is installed by name, and the in-development version from the master branch is installed with the #master suffix.

pkg> add Yao

pkg> add Yao#master

Use the first form unless you specifically need unreleased changes; the README presents the second as "For current master". If the install fails, the README directs you to file an issue at github.com/QuantumBFS/Yao.jl/issues/new rather than to a support channel.

Once installed, the README's first program is a three-line quantum Fourier transform built from blocks. Note that the snippet defines functions only; you still need to construct a register and apply the circuit to see a result, and the README does not show that step.

A(i, j) = control(i, j=>shift(2π/(1<<(i-j+1))))
B(n, k) = chain(n, j==k ? put(k=>H) : A(j, k) for j in k:n)
qft(n) = chain(B(n, k) for k in 1:n)

For a real first use, the README's own pointers matter more than the snippet. The tutorial lives at yaoquantum.org/tutorials, and worked algorithms are collected in the separate QuAlgorithmZoo.jl repository. Start from the tutorial rather than from the three-line example, because the example shows composition style, not the full path from register to measurement.

If you are working from a clone rather than the registry, the Makefile shows the intended developer setup: it activates and instantiates each package under lib/ in dependency order with Pkg.develop, then the root project, then docs. That ordering is not optional; each step develops the packages the next one needs.

Where Yao.jl is the wrong tool

The README states plainly that the project is in an early-release beta and that you should expect rough edges. Treat that as a constraint on adoption, not as boilerplate. A beta label on a framework whose value is composability means the API surface is the part most likely to move, and code written against block constructors is code that may need rewriting.

Three concrete mismatches follow from the repository. First, hardware. Nothing in the README describes submitting circuits to a quantum processor. Yao is a design and simulation framework; the CUDA path is a separate package (CuYao.jl) and is still simulation, on GPUs. If your goal is running on a vendor's device, Yao is not the layer that does it.

Second, language. Yao is a Julia package and installs through Julia's package manager. Teams whose tooling, notebooks and hiring are Python-centred pay a real cost here, and the README offers no Python binding.

Third, scale. The README does not state how many qubits YaoArrayRegister can hold, and it does not describe the tensor-network path as part of this repository; that is YaoToEinsum.jl. For problems where full state-vector simulation is infeasible, the answer is a different package in the same family, not a flag on Yao.

One further gap worth naming: the README documents installation and a first snippet, but it does not document rollback, version pinning or compatibility guarantees between Yao and the lib/ subpackages. That silence is itself information when you plan an upgrade.

How Yao.jl differs from Qiskit and other circuit frameworks

The search data around this project includes people asking whether Qiskit is like Python, which is really a question about what kind of tool a quantum SDK is. The honest comparison is about where the circuit lives.

In Qiskit, circuits are objects built through a Python API and the surrounding ecosystem is Python: transpilers, backends, providers. In Yao.jl, circuits are Julia values built from block constructors such as chain, control and put, and the surrounding ecosystem is Julia packages in the QuantumBFS organisation. The difference that matters day to day is not syntax. It is that a Yao circuit is a first-class Julia object, so a gradient-based optimisation loop, a differential-equation solver or a machine-learning model written in Julia can consume it without a language boundary.

That is also the cost. Qiskit's advantage is breadth of integrations and a much larger pool of existing code; Yao's advantage is that the circuit composes with Julia's numerical stack. If your algorithm work is already numerical and Julia-shaped, Yao's approach is a better fit than porting the circuit into Python and the maths back out. If it is not, the porting cost runs the other way.

Development model, release cadence and upgrade cost

The repository is not archived, and the last push was on 2026-09-09. Recent tagged releases listed for the project are v0.9.3 on 2026-03-01, v0.2.1 on 2026-03-01, and v0.9.2 on 2025-07-10. The two version lines released on the same day are a signal worth noticing: this is a monorepo of separately versioned packages, and the tag numbers do not move together.

Upgrade cost follows from that structure. The justfile shows the release process: a release-patch recipe pulls master, loops over every directory in lib/, runs ion bump patch --no-commit in each, adds the changed Project.toml, then does the same at the root, commits with the message "Bump patch version", pushes, and finally runs ion summon for each lib/ package and for the root. In other words, a single release event touches the root Project.toml and every subpackage manifest at once. If you depend on Yao and on a lib/ package directly, a patch bump can move both, and you should pin versions rather than track master.

The README also mentions a monthly community call, with sign-up by direct message to Roger-luo on the Julia Slack, and a Google sheet for proposing a talk. That is the project's stated channel for roadmap visibility; there is no published deprecation policy in the README or the release notes.

On licensing: the README states that Yao is released under the Apache 2 license, and the repository carries a LICENSE.md file. The repository metadata reports the licence as NOASSERTION, which means automated tooling did not classify it; the README's Apache 2 statement is the project's own. If you redistribute Yao or a derivative, read LICENSE.md and the licences of the lib/ subpackages yourself rather than relying on the metadata field, and take legal advice if the distinction matters to you.

Editorial conclusion

Adopt Yao.jl if your work is quantum algorithm design, circuit construction or teaching, and you are already willing to write Julia. Do not adopt it if you need a hosted backend, a Python-first workflow, or a stable API with no rough edges: the README itself calls the project an early-release beta. Before you commit, verify three things in your own environment: that the stable docs match the version you install, that your problem size fits in YaoArrayRegister on CPU or that you actually need CuYao.jl, and which of the lib/ subpackages (YaoAPI, YaoBlocks, YaoArrayRegister) you are depending on, because the Makefile shows they are developed and versioned as separate packages.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. QuantumBFS/Yao.jl on GitHub
4. README
5. Releases