PennyLaneAI/demos: a notebook gallery and the CLI that publishes it

A gallery of worked examples rather than an importable quantum package

What lives here is a collection of demonstrations, not a library you add to your own code base. The project describes itself as hosting "a collection of demonstrations built with PennyLane, a cross-platform Python library for quantum computing, quantum machine learning, and quantum chemistry," built by researchers for research use. The topic tags the project carries for itself, autograd, automatic-differentiation, qml, quantum-chemistry, quantum-machine-learning, pytorch and neural-networks, tell you the range: the collection starts at introductory concepts and reaches research level algorithms.

That framing decides who should care. A quantum software developer who already knows what a variational circuit looks like and wants a reference implementation can read one, copy the pattern, and adapt it. A student can work through the same files as tutorials. What nobody gets here is an API they can call, because the artifacts are delivered as a Jupyter notebook or a plain Python script rather than as an installed package with a stable function surface. The website entry point is https://pennylane.ai/qml/demonstrations, where each demonstration is available for download in either format.

The demo CLI is a Poetry project named demo, not the demos themselves

The confusion worth clearing up early is that the toolchain and the content have separate identities. The pyproject.toml at the repository root defines a Python project literally called demo, version 0.3.0, whose description repeats the same one line summary of the collection. The version number belongs to the site and CLI tooling, not to any demonstration, which is a detail that matters the moment you try to reason about upgrade risk.

The console entry point is declared like this:

[project.scripts]
demo = "demo.app:app"

The module lives under lib, and the package list points at it:

[tool.poetry]
requires-poetry = ">=2.1"
packages = [
  {include = "demo", from = "lib"}
]

The build itself is handled by poetry-core:

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

So the CLI is installed as an ordinary console script, while the top level entries also include extension.py, conf.py, index.rst and the _templates and _static directories that a Sphinx style documentation build expects. The repository is at once a content collection and a small documentation project, and the CLI is the part that turns the content into a site.

Dependency groups separate building the site from running quantum code

The dependency block in pyproject.toml is not the dependency set of the demonstrations. It is the dependency set of the tooling that publishes them:

dependencies = [
  "typer>=0.15.1,<0.16.0",
  "poetry-plugin-export>=1.10.0,<2.0.0",
  "dulwich<1.3",
  "requirements-parser>=0.11.0,<0.12.0",
  "lxml>=6.1.0,<7.0.0",
  "uv>=0.7.18,<0.8.0",
  "sphobjinv>=2.3.1.3,<3.0.0",
  "pandocfilters>=1.4.0",
  "packaging>=24.0"
]

Reading those names tells you a lot about the pipeline. Typer provides the command line surface, uv and dulwich handle package and repository operations, requirements-parser and packaging read dependency specifications, lxml processes XML, and sphobjinv works with Sphinx inventory files. A separate Dependency Management page is linked at /dependencies/README.md, and a top level dependencies directory exists to hold it.

The dependency groups make the split explicit. A comment in the same file describes base dependencies needed to build the website without any code execution, marked with a *-norun suffix, and warns that updating them requires the accompanying /dependencies/requirements-build file to be updated in step. In practice that means the site can be built and validated on a machine that has no quantum simulator and no GPU, while the real execution environments for individual demonstrations live elsewhere. If you are looking for a single install that gives you every demonstration environment, this repository is not that.

Metadata files and a notebook converter gate what reaches the website

The top level layout shows a publication pipeline rather than a flat set of notebooks. Alongside demonstrations_v2 and lib sit demonstrations_metadata.md, demonstrations_categories.md, demonstrations_statistics.py, a metadata_schemas directory, a notebook_converter directory, module_resets.py and demonstration_categories references in the configuration. A build status badge is also advertised for a workflow named v2-build-branch-master and a separate dev branch workflow, plus an objects.inv Sync Status badge for a workflow that keeps a Sphinx inventory file in step with the published documentation.

The individual artifacts also come in two shapes, a notebook and a script, which is why a converter is needed at all. A single source can be rendered for readers as a notebook and offered to codebases as a Python file, and keeping both consistent is a maintenance task with its own tooling.

Two practical consequences follow. First, the quality bar for a demonstration is set by schemas and statistics rather than by a reviewer opinion, so a malformed metadata entry can block a demo from the site. Second, the two branch workflows mean the content you browse online and the content in the default branch are not guaranteed to be the same snapshot at any given moment. A CLI Tool page at /documentation/demo-cli.md is where the actual commands live. The top level readme lists no install command for the CLI and no flags for it, so a reader who wants to drive the publishing process has to open that separate document.

Apache-2.0 across the collection, with one BSD file carried along

Licensing is simple enough to state precisely. The repository states that everything it contains is free and open source, released under the Apache License, Version 2.0, and pyproject.toml declares the same identifier:

license = "Apache-2.0"

There is a single documented exception. The file custom_directives.py, which is presumably part of the Sphinx extension chain that builds the site, is released under the BSD 3-Clause License with copyright held by the PyTorch contributors dating from 2017. The project asks readers to note this carve out explicitly, which is the kind of detail that matters when you are redistributing a demo inside a larger product.

Without offering legal advice, the practical implication is that a demonstration can be lifted into a commercial or closed source project under the standard Apache 2.0 terms, and you should carry the notice file along with it. The one thing to keep straight is that the BSD grant covers custom_directives.py and not the rest of the tree, so a blanket statement that everything is Apache 2.0 is not quite accurate even though the repository points that way as its main licence.

No releases means no changelog and no compatibility story

The repository has no GitHub releases, and that single fact shapes several practical questions. There is no tag to pin a stable state of the demonstrations to, and no release notes describing when a demo was corrected, which is a meaningful gap in a collection where a subtle change to a Hamiltonian or a data encoding can alter the numbers a reader reproduces.

The Python floor is also explicit and narrow. The project metadata requires >=3.11.0,<3.15.0, so anything on 3.10 or older is out of scope for the tooling, and the upper bound means a new Python release eventually needs a code change. The pinned ranges inside the dependency list are equally tight, with typer held below 0.16.0, lxml below 7.0.0 and uv below 0.8.0. Tight pins make builds reproducible in the short term, and they also mean the tooling stops working when an upstream project crosses a boundary the range forbids, with no release to fall back on.

The last push was on 2026-10-20, so the collection is being worked on. Recent activity is not the same as a compatibility guarantee, though, and no support policy, branch model for long lived maintenance, or statement about which PennyLane versions the demonstrations target is documented. Each demo carries its own environment, so the answer to "which version works here" lives in the individual example rather than at the repository level.

Where the demos sit against reading the PennyLane documentation directly

The alternative for someone learning this area is the PennyLane library documentation on its own. PennyLane is described as a cross-platform Python library for quantum computing, quantum machine learning and quantum chemistry, so the library is the thing you actually depend on at runtime, and its own documentation is where the API contract lives. The difference in approach between that and this repository is one of level and of scope.

A library document tells you what a function accepts and returns. A demonstration shows the whole shape of a problem: how the circuit is built, what is differentiated, which quantities are compared, and how a result is plotted. For quantum machine learning and quantum chemistry in particular, that surrounding structure is where most of the learning happens, and the topic tags on this repository show the range the collection intends to cover, from introductory concepts through to research algorithms.

The cost of that approach is portability. A demonstration encodes an environment that matched the moment it was written, and the per demo dependency handling under /dependencies exists precisely because that environment varies from one example to the next. A reader who wants to reproduce a published figure will spend more time on environment alignment than on reading the code. A reader who wants a stable interface to build on will get little from either the notebooks or the demo CLI.

Editorial conclusion

Adopt this repository when you want a runnable reference implementation of a quantum machine learning or quantum chemistry idea and are comfortable pinning an environment per example. Skip it if you need a stable, versioned API surface, since the repository publishes no GitHub releases and its version field describes the site tooling rather than the demonstrations. Check the dependency set under /dependencies for the specific demo first, then confirm the PennyLane version and hardware or simulator backend it expects before you build anything on top of it.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. PennyLaneAI/demos on GitHub
4. Project website
5. README