Microsoft QDK: the Q# compiler, estimator, and toolchain in one repository

One repository, eleven tools

The microsoft/qdk repository contains tooling for the Q# language, and the first thing it does is enumerate it. That list is the best map of the project there is.

There is the compiler at source/compiler/qsc/, described as the core compiler logic and command-line tooling. There is fuzz testing infrastructure at source/fuzz/. There is a JupyterLab extension at source/jupyterlab/ and a Visual Studio Code extension at source/vscode/. There is the language service at source/language_service/, which provides the Q# language service and editor features, and the standard library at library/. There is an npm package at source/npm/, a simple website for interacting with Q# at source/playground/, the qdk Python package at source/qdk_package/ which is the core Q# Python API with a native Rust extension, the Microsoft Quantum Resource Estimator implementation at source/resource_estimator/, the WebAssembly module bindings and logic at source/wasm/, and the Q# Jupyter widgets Python package at source/widgets/.

The repository also carries the tutorials and samples in the./katas and./samples directories respectively, and the README notes that code from this repository powers the Q# development experience on quantum.microsoft.com.

That last point is the scale indicator. This is not a side project or an experimental tool, it is the implementation behind a shipping product surface, and the components are released together rather than separately.

The project is MIT licensed, the primary language is Rust, the home page is microsoft.github.io/qdk, and the last push to the repository was on 2026-10-19. The recent releases are v1.33.0 from 2026-10-06, v1.32.0 from 2026-09-03, and v1.31.0 from 2026-07-30, so the cadence is roughly monthly.

The compiler is a stack of small crates

The Cargo workspace members list is long, and it is the clearest evidence of how the compiler is put together. There is a base of shared crates such as source/allocator, source/allocator/mimalloc-sys, source/index_map, and source/simulators, and then a sequence of compiler crates that follow the pipeline in order.

The front end is source/compiler/qsc_parse for parsing, qsc_frontend for the semantic work, and qsc_ast for the syntax tree. Above that sits qsc_hir for the high-level intermediate representation and qsc_fir for the fully elaborated form, with qsc_fir_transforms alongside it. Then qsc_lowerer, which lowers the language to something more machine-like, and qsc_codegen for the code generation itself. Around the evaluation side there is qsc_eval, qsc_data_structures, qsc_rir, and qsc_partial_eval, which is the partial evaluation pass.

The pass infrastructure sits in qsc_passes, the documentation generator in qsc_doc_gen, the linter in qsc_linter, the project and file layout handling in qsc_project, and the circuit representation in qsc_circuit. Two compilers sit alongside: qsc_openqasm_compiler for the OpenQASM path and stim_compiler for Stim.

This layering is a compiler architecture choice with real consequences. Splitting the pipeline into a dozen crates with explicit intermediate representations means a change to the lowering rules touches one crate, and it means the partial evaluator and the circuit generator can be developed and tested independently of the parser.

The same care appears in the workspace dependency list. The getrandom entry carries a comment about keeping the rand 0.8 transitive dependency feature-addressable for WASM builds, which is the kind of note that only exists because someone hit the problem. The miette dependency is the diagnostic library, and criterion is the benchmarking framework, with gungraun as a newer addition in the same space.

Building it, and the prereqs script that refuses to proceed

The build has a strict dependency list and a script that checks it, which is the right way to handle a workspace this size.

The requirements are Python, Rust with the wasm32-unknown-unknown target on all platforms for the WebAssembly components, Node.js, a C compiler, wasm-bindgen, and wasm-opt. The last two can be installed into your HOME directory by running python ./prereqs.py --install, and the build script will check these dependencies and their versions and fail if not met. You can also run python ./prereqs.py directly to check the minimum required versions without building anything.

The two rustup commands are the part most people hit:

rustup target add wasm32-unknown-unknown

and on MacOS, both aarch64 and x86_64 targets have to be present or you will encounter linking errors:

rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin

The actual build is one command, python ./build.py, which by default runs a release build of each project, including running tests and checks such as linting. The --help option gives detailed usage.

The Python packages have their own handling. When building the qdk and jupyterlab packages, if the build script does not detect a current Python virtual environment it will automatically create one under source/qdk_package/.venv or source/jupyterlab/.venv, and you can then use those environments to run the tests by activating them with source .venv/bin/activate on Linux and macOS, or .venv/Scripts/activate.bat on Windows.

The Node side is a workspace too, with the qsharp npm package, the playground, and the VS Code extension as members, and it requires Node 22.14.0 or newer. The scripts are eslint and prettier checks with a combined check target.

The playground, and why it exists

The playground is described as a small website that loads the Q# editor, compiler, samples, and documentation for the standard library, and its stated purpose is that it is a way to manually validate any changes you make to these components.

That is a validation harness for a compiler, and it is worth pausing on why it is needed. A compiler change can pass every automated test and still break in ways a human notices immediately, such as an error message that is no longer readable, a doc comment that renders wrong, or a sample that produces a confusing result. The playground puts the editor, the compiler, the standard library docs, and the samples in one page, so a change can be tried in the same shape a user sees it.

The repository layout backs this up. There is a source/playground/ directory with its own README explaining how to build it locally, and a media/ directory for assets. The samples tree is itself a resource, and its directory names describe the coverage: getting_started, language, algorithms, chemistry, notebooks, python_interop, qre, estimation, testing, physical_qubit_addressing, circuit_integration, and OpenQASM.

The katas/ directory is separate and is the tutorials side of the project. The Quantum Katas are the structured exercises that teach the language, and keeping them in the same repository as the compiler means a language change and the exercises that exercise it move together.

The samples tree, which is the best documentation of the language

The samples directory is worth reading as a map of what the toolchain can actually do, because the directory names are the topics.

There is getting_started for the first program, language for the features of Q# itself, and algorithms for the standard set. There is chemistry, which is the domain where quantum computing has the most natural fit. There is notebooks, which is how the Jupyter side is used. There is python_interop, which covers the mixed Python and Q# workflow that the qdk package exists to support. There is qre and estimation for the resource estimator. There is testing for the test tooling. There is physical_qubit_addressing, which is about targeting real hardware rather than a simulator, and circuit_integration and OpenQASM for interop with the wider quantum toolchain.

The samples also carry a samples.mjs file, which suggests the samples are driven from a JavaScript harness rather than only being hand-run, which is how a build script can check that every sample still works.

The resource estimator has its own crate, source/resource_estimator, and a separate source/qre, plus a qdk_openqasm crate and a qsc_openqasm_compiler for the OpenQASM direction. The estimator is the component that answers the question a hardware team actually asks, which is how many physical qubits and how much time a given fault-tolerant algorithm would need.

Citation, and the licensing terms

The README asks for citation in three specific cases, and the forms are worth noting because they distinguish the language from the tooling from the estimator.

For the Microsoft Quantum Development Kit itself, the citation is a software entry with Microsoft as the author, the MIT licence, and the repository URL. For the Q# programming language, the citation is a conference paper from the Real World Domain Specific Languages Workshop 2018, titled Q#: Enabling Scalable Quantum Computing and Development with a High-level DSL, with the full author list and a DOI of 10.1145/3183895.3183901. For the Microsoft Quantum Resource Estimator, the citation is a 2023 ACM publication on using the Azure Quantum Resource Estimator for assessing the performance of fault tolerant quantum computation, by van Dam, Mykhailova and Soeken.

The distinction matters in practice. If you publish work using the Q# language, you cite the language paper, because that is what your work is about. If you publish work using the estimator's numbers, you cite the estimator. The tooling entry covers the rest.

The repository's own licence is MIT, stated in the package manifest, in the workspace package block, and in the LICENSE.txt file. The npm workspace is also MIT licensed and marked private, since it is a build workspace rather than a published package.

The repository also carries a CITATION.cff file, a SECURITY.md, a SUPPORT.md, a CODE_OF_CONDUCT.md, and a CodeQL.yml configuration, so the security and citation metadata are part of the tree rather than an afterthought.

Editorial conclusion

Adopt the QDK if you are writing Q# and want the official compiler, editor support, and resource estimator in one tree, or if you are contributing to the language itself. Do not adopt it as a general quantum simulator stack, since the repository is organised around compilation and tooling. Verify first that your toolchain matches the required versions, because the build script fails outright when the prerequisites are not met.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/qdk on GitHub
3. Project website
4. README
5. Releases