Installation and Compatibility

Installation and Compatibility

Install FlagQuantum in a Python environment that matches your operating system, processor architecture, and execution target.

Scope: FlagQuantum 0.3.1. Checked against the published package metadata, PyPI release files, and tagged release documentation on October 19, 2026. Commands pin the package version for reproducibility. Documentation on the repository main branch may describe newer changes.

1. Version Requirements

Component	Requirement for 0.3.1	Guidance
Python	>=3.10,<3.13	Use Python 3.10, 3.11, or 3.12. Python 3.13 and later are outside this release's declared range.
PyTorch, core package	>=2.10,<2.15	The release README reports compatibility CI for 2.10.x–2.14.x. For new upstream CPU/CUDA environments, it recommends 2.13.x or 2.14.x.
PyTorch, invertible extra	>=2.13,<2.14	This extra narrows the core range to 2.13.x. Do not add it to a 2.14.x environment.
NumPy	Optional for the core installation	Included in the commands below to avoid PyTorch's missing-NumPy warning. Optional features can impose their own NumPy requirements.
GPU	Not required for local CPU simulation	Accelerator execution requires the appropriate PyTorch runtime, drivers, and supported workflow.

A dependency range indicates package compatibility, not validation of every platform, accelerator, or feature combination. Consult the release capability catalog for workload-specific support.

2. Choose Your Platform

Platform	Published 0.3.1 binary wheel	Installation path
macOS, Apple Silicon / ARM64	Yes: macosx_11_0_arm64	Follow the Apple Silicon steps below. The complete environment must also satisfy PyTorch's OS requirements.
Linux, x86-64	Yes: manylinux_2_24_x86_64.manylinux_2_28_x86_64	Use a compatible glibc-based distribution and the CPU or NVIDIA CUDA steps below. The wheel tags describe FlagQuantum's binary baseline; dependencies may require newer system components.
Windows, x64	Yes: win_amd64	Use 64-bit Python and the CPU or NVIDIA CUDA steps below.
macOS, Intel x86-64	No	The release README does not support this as a binary installation target. Review source-build requirements before attempting a custom build.
Linux ARM64, Windows ARM64, 32-bit systems, or musl-based Linux	No matching wheel in this release	A source archive is published, but its availability does not establish support or successful compilation on these platforms.

The wheels use the cp310-abi3 tag. That does not override the package's Python requirement: stay within Python 3.10–3.12. See the published release files.

3. Create an Environment

macOS and Linux

Choose an installed Python 3.10–3.12 interpreter. This example uses Python 3.12:

python3.12 --version
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

If your supported interpreter is named python3, substitute that command. If Linux reports that venv is unavailable, install the matching Python venv package through your distribution's package manager.

Windows PowerShell

py -3.12 --version
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

If script execution prevents activation, use .\.venv\Scripts\python.exe instead of python in subsequent commands. You can install and run packages without changing the execution policy.

4. Install on macOS with Apple Silicon

Inside the activated environment:

python -m pip install "torch>=2.13,<2.15"
python -m pip install --only-binary=flagquantum "flagquantum==0.3.1" numpy
python -m pip check

Use an ARM64 Python interpreter. The --only-binary=flagquantum option makes pip report a missing compatible FlagQuantum wheel rather than unexpectedly attempting a source build. These steps establish a local CPU environment; they do not establish Apple MPS accelerator support.

5. Install on Linux or Windows with CPU-only PyTorch

Inside the activated environment, run the same commands on either platform:

python -m pip install "torch>=2.13,<2.15" --index-url https://download.pytorch.org/whl/cpu
python -m pip install --only-binary=flagquantum "flagquantum==0.3.1" numpy
python -m pip check

Expected dependency check output:

No broken requirements found.

An NVIDIA GPU or CUDA installation is not needed for these CPU examples.

6. Install for NVIDIA CUDA

1. Create a fresh supported Python environment.
2. Open the official PyTorch installation selector and choose your operating system, pip, and a CUDA build compatible with your NVIDIA driver.
3. Install a PyTorch 2.13.x or 2.14.x CUDA build. If the selector defaults to a newer PyTorch release outside FlagQuantum's range, consult PyTorch's version-specific installation commands.
4. Install FlagQuantum and verify the CUDA runtime:

python -m pip install --only-binary=flagquantum "flagquantum==0.3.1" numpy
python -m pip check
python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA build:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available())"

For a working CUDA environment, the last line should report CUDA available: True. A successful CPU smoke test alone does not verify GPU execution. Choose an explicitly supported accelerator workflow from the capability catalog.

The optional cuda extra adds triton>=3.1,<4; it does not install the NVIDIA driver or choose a CUDA-enabled PyTorch build. Install it only when your workload and Triton's platform requirements call for it:

python -m pip install "flagquantum[cuda]==0.3.1"

7. Use a Vendor-managed Accelerator Environment

The release README lists Hygon DCU, Moore Threads MUSA, MetaX, and Biren paths using vendor-provided PyTorch runtimes. Start from the vendor's documented environment or container and retain its runtime.

1. Check Python, architecture, and the installed vendor PyTorch version.
2. Confirm that the runtime meets torch>=2.10,<2.15 and that the intended workflow supports the device.
3. Preview dependency resolution before installing:

python -c "import sys, torch; print(sys.version); print(torch.__version__)"
python -m pip install --dry-run "flagquantum==0.3.1"

4. If the plan retains the vendor runtime, install using the vendor's package-index and wheel guidance:

python -m pip install "flagquantum==0.3.1"
python -m pip check

Compatible local version labels, such as 2.10.0+metax3.8.1.0, are accepted by the core requirement. Avoid replacing the vendor runtime with an upstream CPU/CUDA wheel or using eager dependency upgrades. If the version is incompatible, follow vendor guidance rather than forcing installation with --no-deps. The invertible extra requires PyTorch 2.13.x and is not a vendor-runtime installation shortcut.

8. Optional Features

The basic CPU examples require no extras. Install only the integrations you need; their own platform and dependency constraints still apply.

Extra	Additional requirement declared by 0.3.1	Purpose
viz	matplotlib>=3.5.0	Plotting support
jax	jax>=0.10,<0.11	Optional JAX integration; check JAX's own Python and accelerator requirements
cotengra	cotengra>=0.8,<0.9	Optional contraction planning
stim	stim>=1.16,<2	Stabilizer sampling
pymatching	pymatching>=2.3,<3	Optional matching-decoder integration
qiskit	Qiskit >=2,<3, Aer >=0.17,<1, SymPy >=1.13,<2	Qiskit interoperability
pennylane	Python 3.11+; PennyLane >=0.44.1,<0.46	PennyLane interoperability
cirq	Python 3.11+; Cirq Core >=1.6.1,<1.8	Cirq interoperability
braket	Python 3.11+; Amazon Braket SDK >=1.117,<2	Braket integration
quafu	Python 3.12; QuarkCircuit >=0.5.13,<0.6	Optional Quafu dependencies; the separate QSteed compiler plugin is not included
azure	qdk[azure]>=1.32.3,<2	Azure Quantum integration
cudaq	Python 3.11+; CUDA-Q >=0.15.1,<0.17	CUDA-Q integration, subject to its platform requirements
invertible	PyTorch >=2.13,<2.14	Optional invertible integration

For example:

python -m pip install "flagquantum[viz]==0.3.1"
python -m pip check

Python markers on extras can skip dependencies on older interpreters without installing a usable integration. For example, installing the quafu extra on Python 3.11 does not install its Python 3.12-only dependency. Provider SDK installation also does not configure credentials, grant service access, or certify hardware execution.

9. Verify the Installation

Save the following as verify_install.py:

from importlib.metadata import version
import platform
import sys
import torch
import flagquantum as fq

print("Python:", sys.version.split()[0])
print("Platform:", platform.system(), platform.machine())
print("FlagQuantum:", version("flagquantum"))
print("PyTorch:", torch.__version__)

result = fq.run(fq.Circuit(2).h(0).cx(0, 1), outputs=fq.probabilities())
probabilities = result.probabilities[0]
expected = torch.tensor([0.5, 0.0, 0.0, 0.5], dtype=probabilities.dtype)
assert torch.allclose(probabilities, expected, atol=1e-6)
print("Bell probabilities:", [round(p.item(), 6) for p in probabilities])
print("CPU installation check passed.")

Run:

python -m pip check
python verify_install.py

Output from the local verification environment:

Python: 3.12.14
Platform: Darwin arm64
FlagQuantum: 0.3.1
PyTorch: 2.14.1
Bell probabilities: [0.5, 0.0, 0.0, 0.5]
CPU installation check passed.

Python, platform, and PyTorch lines vary by environment. This page's local execution evidence covers Apple Silicon CPU only; the other installation paths are documented from release sources, not claimed as locally tested.

10. Source and Development Installation

Use a separate development environment. A source installation requires the repository's native-extension build prerequisites and suitable compiler tooling; it is not a universal workaround for unsupported platforms.

The v0.3.1 contribution guide uses this CPU development setup after cloning and entering the repository:

git clone --branch v0.3.1 https://github.com/flagos-ai/FlagQuantum.git
cd FlagQuantum
python -m pip install --upgrade pip setuptools wheel
python -m pip install "torch>=2.13,<2.14" --index-url https://download.pytorch.org/whl/cpu
python -m pip install --no-build-isolation -e ".[dev]"

On Apple Silicon, use the default PyPI index for the PyTorch command instead of the CPU-only index. For accelerator development, substitute the appropriate upstream or vendor runtime command. --no-build-isolation reuses the intentionally selected runtime for the editable build; official isolated builds separately declare a PyTorch 2.10.x build dependency. These build-time and runtime requirements serve different purposes.

For container-based development, see the release container guide.

11. Troubleshooting and Reproducibility

Problem	Next step
No matching distribution	Check Python version, 64-bit architecture, OS, and wheel availability. Update pip in a fresh environment.
macOS unexpectedly uses x86-64 Python	Check python -c "import platform; print(platform.machine())"; select an ARM64 interpreter on Apple Silicon.
pip starts compiling FlagQuantum	Check whether a matching wheel exists. Use --only-binary=flagquantum when you intend a binary installation.
PyTorch dependency conflict	Check core versus extra-specific ranges, especially invertible. Use a separate compatible environment.
Import or native-library load failure	Check the selected Python/PyTorch environment and OS requirements. Retest in a clean environment with an official wheel.
CUDA available: False	Check whether PyTorch is a CPU build, whether the GPU is visible, and driver compatibility with the selected CUDA build.
Import works but a provider call fails	Follow that integration's dependency, credential, and execution documentation. A local smoke test does not validate remote access.

Record package versions after a successful installation:

python -m pip freeze > requirements-lock.txt

This records Python packages, not GPU drivers, operating-system libraries, or provider configuration. Include those details when reproducing an accelerator run. For unresolved problems, open an issue with platform details, versions, commands, and the complete error, removing credentials before posting.

Next Steps and Sources

• Accelerator Setup: runtime detection, explicit device execution, and gradient/optimizer checks.
• Quick Start: complete circuit and training examples.
• Wiki Directory.
• PyPI 0.3.1 release files: published wheel platforms.
• Tagged README: recommended installation paths and runtime compatibility.
• Tagged package configuration: Python, dependency, extra, and build requirements.
• Tagged contribution guide: editable development setup.