Yao.jl is a seven package Julia monorepo whose release script pushes straight to master

Seven packages, and the root is developed last

Yao is not one package on disk. It is a root package plus six subpackages under `lib/`, and the root depends on all six. The Makefile spells out the order in which they have to be initialised, and the order is not alphabetical.

YaoAPI goes first with nothing to develop. YaoArrayRegister second, developing YaoAPI. YaoBlocks third, developing the first two. YaoSym fourth, depending on YaoArrayRegister and YaoBlocks. YaoPlots fifth, depending on YaoBlocks and YaoArrayRegister. YaoToEinsum sixth, depending on YaoBlocks. The root Yao package seventh, developing all six. The documentation environment last, developing all six again.

Each step is a Julia call that activates the subdirectory, develops the packages it needs by path, and instantiates. So a clone is not usable until that target has run, and a reader who tries the obvious thing first will hit an environment error that says nothing about the missing subpackages.

The payoff of the arrangement is that the subpackages are independently versioned and independently releasable, which is exactly what the release history shows and what the next two sections are about.

One recipe pulls master, pushes master, and then summons a release

The repository ships a `justfile` as well as a Makefile, and the justfile has a single recipe called release-patch. It is a bash script, and it does this:

It sets `set -e` for fail-fast behaviour, pulls the default branch, and pushes it straight back. Then it loops over every directory under `lib/`, and in each one bumps the patch version without committing, adds the manifest to the index, and moves on. It does the same bump for the root manifest. Then it checks whether either the working tree or the index differs, and if so commits with the message about bumping the patch version, and pushes again. Finally it summons a release for each subpackage with notes skipped, and then summons one for the root.

Three things follow from reading it. Every patch release bumps the version of all seven packages, so a one line change in one subpackage advances six others. The push to the default branch is the first and last network operation, so the working branch and the release state are the same ref. And there is no tag creation and no pull request anywhere in the recipe, which makes the moment a release appears a function of a local script having been run.

Two version lines were tagged in the same minute

The release list explains the monorepo immediately. The three most recent tags are v0.9.3, published at 06:52:33 on 2026-03-01; v0.2.1, published at 06:51:42 on the same date; and v0.9.2, published on 2025-07-10.

Two versions, published fifty-one seconds apart, at numbers that have nothing to do with each other. That is what independently versioned subpackages look like from the outside: one of them is a mature line approaching 1.0 and another is young and still in its second minor. The root package version and the root version line are the ones a user sees in the package manager, and the subpackage versions are the ones the release recipe walks.

So the version you depend on is the root's, and the versions in the other six are internal bookkeeping. Nothing on the page explains this, and a reader who follows the release list will conclude that something is broken rather than that the repository is a monorepo.

The page calls itself a beta, and asks you to cite a 2019 preprint

Two statements in the introduction bracket the project's own self-assessment. It says the framework is designed around quantum algorithm design, quantum software 2.0, and quantum computation education. Then it says the project is in an early release beta and to expect some adventures and rough edges, while the root tag is at 0.9.3.

The example is three lines, and it is a quantum Fourier transform written with the block API rather than with matrices:

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)

The first line builds a controlled phase shift, the second chains blocks for a size and a register with a Hadamard at one position, and the third chains those across the registers. There is a small inconsistency in the example worth noting for anyone copying it: the first two functions are written with domain type parameters in their signatures and the third is not, so the entry point of the example is untyped while the parts it calls are not.

Then the citation request, which asks for a 2019 arXiv preprint with four authors, while the team section names two current maintainers. A citation that has not been updated in seven years is worth a glance before you reuse it.

Two install tracks, and the acceleration lives in sibling repositories

Yao is installed the standard way for a Julia package: open the interactive session, press the square bracket to get to package mode, and add it.

pkg> add Yao#master

The stable form takes no ref and the form above tracks the current master branch. Since the default branch is master rather than main, the two-word ref is not a detail: it is the difference between a released version and whatever is at the branch head.

Acceleration is not in this repository. CUDA support is a separate package called CuYao.jl, and tensor network based simulation is another called YaoToEinsum.jl, both under the same organisation. The same split shows up in the Makefile, where YaoToEinsum is one of the six subpackages developed locally, which suggests the local layout and the published layout are not identical.

The page also names an algorithm collection as a third repository, where some algorithms are implemented, and points at a tutorial site for learning. So the install gives you an engine, and the examples live next door.

Two citation files, two changelogs, an agent file, and a CI directory

The top level is worth reading as a list of what this project considers separate concerns. There is a `CITATION.bib` and a `CITATION.cff`, so the citation exists in both BibTeX and the newer YAML format. There is a `HISTORY.md` and a `NEWS.md`, which is two changelogs rather than one. There is a `CLAUDE.md` for agent instructions, and a `.ci/` directory that sits next to `.github/`, so continuous integration is split between the platform's directory and one of its own.

The rest is ordinary Julia packaging: `Project.toml` at the root and in each subpackage the Makefile activates, `src/`, `test/`, `docs/`, `ext/` for package extensions, `notebooks/` for examples, and `lib/` for the subpackages themselves.

The licence is the one thing the page states plainly. It says Yao is released under the Apache 2 licence, and there is a `LICENSE.md` at the root. The repository's own licence field, meanwhile, is empty rather than filled with an identifier, so the two are consistent and one of them is simply unset.

Three documentation paths and a community call run through a spreadsheet

Documentation is versioned three ways, and the links make the distinction explicit. There is a stable path for the most recently tagged version, a latest path for the in-development version, and a dev path. The badge definitions at the bottom of the page give a stable badge and a dev badge, while the list in the text links stable and latest, so the dev path is reachable from a badge and the latest path from the list.

The project also runs a monthly community call, and the sign-up procedure is specific. You send a direct message with your email address to one named maintainer in the Julia Slack channel, or you follow the project's account elsewhere, and then you add a topic to a shared Google spreadsheet. Sessions are either forty minutes to share something or ten minutes to talk.

The rest of the communication surface is spread across four places. Questions and bugs go to GitHub issues, there is a channel in the Julia Slack workspace, and there are two discourse forums, the English one and a separate Chinese-language one, both named on the page.

That last detail is the unusual one. A Julia package maintaining a second discourse community in another language is a deliberate cost, and it is the clearest signal in the repository about who the project expects to use it.

Editorial conclusion

This fits someone teaching or prototyping quantum circuits who wants circuits rather than matrices, and who is comfortable with a Julia package that spans several subpackages. Four things to check first. Whether you want the stable release or the master branch, since one install command tracks a moving branch and the default branch is master rather than main. Whether the seven package dev order matters to you, which it only does if you intend to work from a clone, and if you do then the initialisation target is the entry point rather than a package instantiate. What the release recipe implies about the repository, since it pushes to the default branch and then summons releases with no tag step and no pull request in the loop. And whether the licence suits you, since the text says Apache 2 and the file is at the root but the repository's own field is empty, and you should confirm rather than infer.

Frequently asked questions

Official sources

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