qiskit-machine-learning links to Qiskit 1.4 docs and requires Qiskit 2.0, and pins its macOS test concurrency to two

IBM wrote it, the Hartree Centre maintains it, and two copyright lines say so

The library is part of the Qiskit Community ecosystem, a set of higher level libraries built on the Qiskit software development kit. From version 0.7 it is co-maintained by IBM and the Hartree Centre, which is part of the UK Science and Technologies Facilities Council.

The repository makes the transition visible in its own headers. The packaging file carries two copyright lines, one for IBM covering 2021 to 2026 and one for UKRI-STFC at the Hartree Centre covering 2024 to 2026. So the first author arrived a few years before the second, which matches a project that started inside a company and was later handed shared maintenance rather than transferred.

The structure of the library is documented in a paper rather than only on the website: an arXiv entry linked from the file describes the library structure, its features and its domain specific applications. The site is used for usage and API reference instead.

That combination, a paper for shape and a site for mechanics, is the arrangement most of the Qiskit community libraries use, and it means the fastest summary of what the components are is a PDF rather than a table.

The primitive links point at Qiskit 1.4 documentation and the dependency floor is 2.0

The two neural network primitives are documented by linking to the IBM Quantum API pages, and both links carry the version in the path. The Estimator link ends in the primitive documentation for Qiskit 1.4, and the Sampler link does the same.

The requirements file asks for `qiskit>=2.0`. So the reference links in this file point at documentation for a major version that the package refuses to run against, and that mismatch is in the file a reader is most likely to click.

That is not a hypothetical annoyance. The whole design of the two primitives is built on those objects, and the shape of what you pass to them, a circuit plus observables for one, a circuit plus a parameter set for the other, is the part that moves between major versions.

The fix is trivial and the note is worth making because the file is otherwise careful: treat the links as history, not as reference, and read the current primitive documentation for whatever Qiskit you actually installed. Nothing in the requirements or the readme warns you that the two disagree.

The dependency floors come from different eras of the same ecosystem

The install is one line, and the sentence next to it is the important part:

pip install qiskit-machine-learning

The file says pip will install all dependencies automatically, so that you always have the most recent stable version. That is a promise about floating versions, not about pinned ones.

The requirements file is six lines and worth reading in order, because the floors do not share a vintage. `qiskit>=2.0` and `numpy>=2.0` are the strictest, both requiring recent major releases. `scipy>=1.4` and `scikit-learn>=1.2` are considerably older floors, from before NumPy 2 existed. Then `setuptools>=40.1` and `dill>=0.3.4`, where dill is there for serialising objects and setuptools is a packaging tool that has no business being a runtime requirement at all.

Two consequences. A floor of SciPy 1.4 is not a usable constraint alongside NumPy 2, so in practice the resolver will pick a modern SciPy and the stated floor is decorative. And with no upper bounds anywhere, that sentence about recent stable versions is literally true: your SciPy, NumPy and Qiskit versions float with whatever the index serves, so two environments that installed the same version of this library can differ substantially underneath.

For a research library that is a reasonable trade. For a production service that vendors its dependencies, it means the lock file is not optional.

Test concurrency is computed differently on each platform, and macOS is fixed at two

The Makefile decides how many test workers to use with a chain of conditionals that is worth reading as a curiosity.

First it asks the operating system for a processor count. On Linux it counts processors from the system files. On macOS it does not ask at all and sets the count to two, whatever the machine is. Everywhere else it sets the count to zero.

Then it maps that count to a concurrency value through a second chain of exact comparisons. A count of two gives two workers, one gives one, three gives three, and zero gives zero, which reads as unlimited. Anything else falls through to a shell expression that divides the count by two and rounds it.

So the results are uneven in a specific way. A four core Linux machine and a four core macOS machine both get two workers, though for different reasons. A sixty four core Linux machine gets thirty two, which is a lot of parallel test processes for a scientific package. A two core Linux machine gets the same two workers as a sixty four core macOS machine.

The CI target prints the detected count and the chosen concurrency before running, which is the kind of thing that saves an hour of debugging on someone else's machine, and the local test target bypasses the machinery entirely by calling the unittest discovery module directly.

The version is a text file read at build time, and the build refuses old setuptools

The packaging script does not take the version from the project configuration. It opens a version file inside the package directory, strips it, and passes that string to setuptools as the version.

It also gates its own execution on the packaging tool. Before doing anything, the script checks whether the installed setuptools exposes the namespace package finder, and if it does not, it prints a message naming the installed version, tells you that PEP 420 support is missing, asks you to upgrade to 40.1.0 or newer, and exits with a failure code. That is a hard stop at build time rather than a warning, and it matches the 40.1 floor in the requirements.

The long description is read from the readme and then filtered: a regular expression strips everything between the long description skip begin and long description skip end markers, which is how the badge block at the top is kept out of the PyPI page while the prose stays.

The version file also means the number on the package index and the number in the repository come from the same place, which is the right arrangement, and it is why nothing in the project configuration needs to be edited at release time.

Two primitives decide what a quantum neural network hands back

The neural network interface is generic, and exactly two classes implement it, and the difference is what comes out.

`EstimatorQNN` uses the estimator primitive. It pairs a parametrised quantum circuit with quantum mechanical observables, and its output is the expected value of the observable. That is a number per observable, which is the shape a classical loss function wants.

`SamplerQNN` uses the sampler primitive and translates bit string counts into the desired outputs. That is a distribution rather than an expectation, and it is what you need for a sampling style objective.

Training on top of those is handled by a classifier and a regressor, and above those sit the variational quantum classifier and the variational quantum regressor, which take a feature map and an ansatz and assemble the network for you with high level syntax. So the ladder is primitive, then two derived primitives, then trainers, then the two variational algorithms that most examples use.

The kernel side is a separate path. The fidelity quantum kernel computes kernel matrices for a dataset using a fidelity measure, and those matrices feed a quantum support vector classifier or a quantum support vector regressor for classification and regression. The file also notes that the kernel is compatible with classical kernel based machine learning algorithms, which means the matrix can leave the quantum stack and be handed to something else entirely.

The PyTorch connector is the part that leaves the quantum stack

A single connector class is what makes these networks usable inside an ordinary training loop.

`TorchConnector` takes a quantum neural network and exposes it to PyTorch. The library supplies the gradient algorithms, so the integration includes automatic differentiation rather than a hand written gradient step, and the gradients PyTorch computes during backpropagation account for the quantum network as part of the model rather than treating it as an opaque callable.

That is the whole point of the design. With a differentiable boundary, a quantum layer can sit in the middle of a classical network and be trained by an optimiser that knows nothing about it.

The file also notes that the design allows connectors to other packages or accelerated libraries to be built, which is the extension point if your training loop is not PyTorch.

PyTorch is an optional extra rather than a dependency, installed with the torch extra, and the same paragraph says the connector is what facilitates hybrid quantum and classical networks once it is present. Sparse is the other optional extra, and it is a separate project built on NumPy and SciPy's sparse arrays.

The lint configuration disables things in writing, and two tools guard the edges

The quality configuration is where a maintained scientific library shows its habits.

Pylint runs with two extra plugins, one for parameter documentation and one for docstring style. The spell checker is wired to an English dictionary with a private word list checked into the repository, so that quantum vocabulary does not produce noise. The formatter is set to a hundred character line length and targets Python 3.10 through 3.13, and the linter's own line length allowance is five characters wider, at 105.

What is disabled is annotated. Spelling is off because it is too noisy. The fixme checker is off so that TODOs do not become warnings. Duplicate code detection is off because it is too verbose. Import errors are off because they are overzealous with optional and dynamically imported packages. The naming rules allow a long list of short names, quantum abbreviations included, so that a variable called q or a gate named iSwapGate does not have to be renamed to satisfy a linter.

Two small tools sit alongside the linters and run in the lint target: one verifies licence headers on every source file, and one looks for release notes that were added outside the notes directory.

The root also carries an agent policy file, a security policy, a citation file, a conduct code, a merge queue configuration, a mailmap, and a list of revisions to exclude from blame.

Editorial conclusion

qiskit-machine-learning is worth trying if you already work in Qiskit and want a fidelity kernel, a variational circuit or a PyTorch hybrid without writing the plumbing. Three things to check first. Read the dependency floors before you pin anything, because Qiskit 2.0 and NumPy 2.0 sit beside a SciPy floor old enough to predate them, so a working environment is one pip resolve away from a surprise. Note that the primitive links in the file point at Qiskit 1.4 documentation while the floor is 2.0, so check the current API pages rather than those links. And if you plan to run the test suite on a laptop, expect the concurrency to be fixed at two workers on macOS regardless of the machine.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. qiskit-community/qiskit-machine-learning on GitHub
4. README
5. Releases