Qiskit Ecosystem project overview

The Qiskit Ecosystem consists of projects, tools, utilities, libraries and tutorials from a broad community of developers and researchers. The goal of the Ecosystem is to recognize, support and accelerate development of quantum technologies using Qiskit.

Background

As number of projects in Qiskit ecosystem is growing, we found it useful to create a curated list of libraries, open source repos, guides, games, demos, and other resources in order to accelerate development of quantum technologies and provide more visibility for community projects.

Adding a project to the ecosystem

Anyone can add their project for review to be included in the ecosystem by submitting an issue. A submission is reviewed against the same check ups that keep running afterwards, so a project joins by passing them and stays by keeping them passing.

Check ups

Membership in the Qiskit Ecosystem is not a one-time decision: it is checked continuously. A check up is a single, named membership criterion, such as "have a commit within the last 12 months" or "have an OSI-approved license".

Every check up has:

an id of three characters, like [G07] or [001], which is what shows up in the project pages and in the project data,
an importance, which determines how much time there is to fix it (see below),
a category, which says what kind of criterion it is (see below),
an applies to, since not every criterion makes sense for every project. For example, Python packages check ups are only run on projects that publish to PyPI.

All the check ups are declared in resources/checks.toml, which is the single source of truth: the check up list and every project page are generated from it. Most check ups also declare a checker, which is the PyTest test that implements them, under ecosystem/validation/. For instance, [G07] is implemented by test_github.py::test_G07.

Importance and cure period

Every check up has a cure period: how many days a member can keep failing it before losing its membership. A cure period of 0 days means the check up has to pass at all times, while no deadline (cure_period_in_days = -1) means the opposite: the check up shows up as pending, so the project is Under revision, but it never retires the project on its own.

The cure period is a property of the check up, and most check ups do not state one: they take the default of their importance level.

importance	description	default cure period
CRITICAL	This is a must-pass and there is no room for negotiation. Failing this test results in immediate removal.	0 days
IMPORTANT	If this check is on a candidate, the merge won't happen until the check passes. If it affects an existing member, there will be a cure period for fixing it.	90 days
STRONG-RECOMMENDATION	This is a strong recommendation that can be waived if there is a really really good reason for it.	90 days
RECOMMENDATION	This is a recommendation. You might have to argue why this check does not apply to a specific project.	180 days
LEGACY	This validation no longer applies.	no deadline

The cure period each check up ends up with is in the check up list.

When automation runs

All the automation run by GitHub Actions:

Daily, Daily | Update member data refreshes the data that the check ups look at (GitHub repository activity, PyPI and Julia package metadata, ...) and commits it into the project files. This is why a fix in a project can take a day to be visible, and a release can take a day to be noticed.
Weekly (Thursdays), Weekly | Update member status runs python manager.py members update_checkups on every non-alumni member, and then recomputes the membership status with python manager.py members update_status. The result is not pushed directly: it opens a pull request labeled member update, so a human reviews any status change before it reaches the website.
Both commands take -e, a list of things to leave out of the run. A value is a check up importance or category ("a check up of this kind does not change the status"), or a membership status ("projects already in this status are left alone"). So the weekly run is update_checkups -e alumni followed by update_status -e "recommendation, alumni, qiskit-project": alumni stay alumni, Qiskit Projects are governed differently, and a recommendation alone is not enough to put a project under revision.
On submission and on member updates, Member validations runs the check ups on the single project of the pull request. A new candidate has to pass everything but the recommendations before it can be merged.

How a failing check up is recorded

Each member is a TOML file under resources/members. A check up that does not pass is stored there as a [checks.<ID>] table:

[checks.P10]
since = 2026-07-09
details = "Python package qiskit-algorithms declared itself compatible to a not-yet-released major version of Qiskit"

since is the date the check up started failing. It is not reset while the check up keeps failing, so since + cure period is the deadline.
details is the assertion message of the checker: the concrete reason, with the offending package, URL or date.
discussion and source may point to the issue where the situation is being discussed or tracked.

A passing check up leaves no trace: if the failure is fixed, the whole [checks.<ID>] table disappears on the next weekly run, and with it the deadline.

Check ups that are not tests

Some criteria cannot be tested automatically: whether a project interfaces with Qiskit in a meaningful way, for example, or whether a primitive implementation is V2-compatible. Those check ups have no checker. Instead, they are created by a human and carry a source, the URL of the GitHub issue where the problem is tracked, usually in the project's own repository:

[checks.Q20]
since = 2026-09-15
source = "https://github.com/rigetti/qiskit-rigetti/issues/53"

For these, the weekly run does not execute a test: it looks at the state of that issue. If the issue is closed, that is noted in details (the source issue is closed as completed, for instance) and a human decides what to do. A closed issue does not remove the check up by itself, because closing an issue does not necessarily mean the situation is solved.

Expected failures

A check up can be failing for a good reason. In that case, a maintainer of the Qiskit Ecosystem adds an xfailed entry with the explanation, and the failure stops counting towards the membership status:

[checks.G07]
xfailed = "The project is feature-complete and the maintainers still answer issues"
xfailed_until = 2027-01-31

xfailed_until is optional and makes the explanation expire. An explanation without it never expires. Once the date passes, the check up is evaluated as a regular one again, which is a way of saying "this is fine for now, let us look at it again in six months".

The whole list

Every check up, with the projects that are currently failing it, is listed in Check ups.

For project maintainers

Your project is a member of the Qiskit Ecosystem, and the check ups above run on it every week. Here is what that means in practice.

Where to see how your project is doing

Your project page (https://qiskit.github.io/ecosystem/p/<short uuid>/) has a Checkups section. If everything passes, it says All good. Otherwise, it lists one line per failing check up: the icon is the importance, the [ID] links to that check up, and the text is the concrete reason.

The badge is the other signal: it turns orange when the project is Under revision, so adding it to your README.md is also a way of noticing that something needs your attention.

What happens if a check up fails

Failing a check up is not an immediate removal, unless its importance is CRITICAL. The project moves to the Under revision status and the cure period of the check up starts counting from its since date. If it is still failing (and unexplained) when the cure period is over, the project becomes Alumni and is removed from the website.

Being Alumni is reversible: a project can be reconsidered at any point by opening a pull request that removes the member.status entry from its TOML file.

What you can do about it

Fix it upstream. Most check ups look at your repository or at your published packages, so the fix lives there: a release compatible with the latest Qiskit, a LICENSE file GitHub can recognize, a commit. The data is refreshed daily and the check ups run weekly, so give it a few days before worrying.
Fix the metadata. Some check ups are about what the Qiskit Ecosystem knows about your project (a broken URL, a too-long description, a wrong category). Those are fixed in your project's TOML file, either with a pull request to this repository or by opening an update issue.
Explain it. If a check up genuinely does not apply to your project, say so in an issue. If we agree, it is recorded as an expected failure and stops affecting your status.
Declare your support expectations. A project that is intentionally not maintained anymore is not a problem, as long as it says so: setting the maturity to as-is or deprecated marks it as Unmaintained and exempts it from the activity check ups.

Where to ask

Open an issue in the Qiskit Ecosystem repository.
Ask in the #qiskit-ecosystem Slack channel (sign up if you are not in the workspace yet).

Architecture

The rest of this page is about how the repository itself is put together, which is what you need when changing the Qiskit Ecosystem rather than taking part in it.

Everything is designed to run through GitHub Actions, so the ecosystem Python package is a runner of CLI commands to be executed from steps in those workflows. There is no server and no database: the member files in the repository are the data, and the website is a build artifact.

The entrypoint is the manager.py file in the root of the repository.

python manager.py <CMD> <NAME_OF_FUNCTION_IN_MANAGER_FILE> <POSITIONAL_ARGUMENT> [FLAGS]

The commands that run the check ups (members update_checkups and members update_status) are the ones described in When automation runs.

Storage

We store each member of the ecosystem as a TOML file under resources/members; these are the files you should edit when adding / updating members to the ecosystem. Access to these files is handled programmatically through the DAO class.

Webpage

This documentation site is built with ProperDocs (the drop-in continuation of MkDocs 1.x) from the docs/ directory, configured in properdocs.yml. Some of its pages are not written by hand: the project pages under docs/p/ are generated at build time from the member files, and the tables injected with read_raw/read_json come from docs/assets/, which is regenerated by python manager.py members update_docs_assets.

To build everything, run:

tox -e website

The result lands in website/, and a GitHub action publishes it on every push to main. Besides the pages, the command generates:

website/ecosystem.json, the machine-readable dump of all the member data,
website/b/, the shields.io endpoints behind the badges,
website/index.html, an HTML file that redirects to the ecosystem page. This is needed because we used to host the ecosystem page on GitHub pages, so it overwrites the index that ProperDocs generates.

category	description
SUBMISSION	Validations done once when a project is submitted.
METADATA	There is an issue about the member metadata used in the ecosystem. It is not an upstream error.
GENERAL	General criteria that might be implemented differently, depending on the project. Check the "related to" validations to see which might apply to a specific repository, software, or package.
ACTIVITY	The project might not have a level of activity to be considered well-maintained.
OSS	There is an issue with some of the open-source aspect of the project.
OUT-OF-DATE	The project might not follow the last best-practices or connects to Qiskit in a way that is considered old-fashioned, currently unsupported, or deprecated.
BEST-PRACTICE	The project might not follow software general best-practices.