Seeking best practices for fully reproducible Qiskit installations across heterogeneous environments, including Aer GPU and offline/HPC use cases.
Target scope
- Operating systems: Windows 11 (x86_64), Ubuntu 20.04/22.04 and RHEL 8/9 (x86_64), macOS 13-15 (arm64).
- Python versions: 3.11 as baseline; 3.12 where feasible.
- Packages: qiskit-terra, qiskit-aer (CPU and GPU), qiskit-ibm-provider, plus common ecosystem libraries (algorithms, experiments, optimization as applicable).
- Requirements: deterministic builds from lock files; minimal external toolchain requirements; offline install via a pre-built wheelhouse; container-friendly (Docker/Apptainer) and HPC module-friendly.
Current approach and pain points
Questions for the community
1) Is there an official constraints or “lock” file per Qiskit release (or a documented dependency matrix) that can be used to produce hermetic, repeatable installs across Python 3.11/3.12?
2) Is there a maintained support matrix mapping:
- Python versions to qiskit-terra, qiskit-aer, qiskit-ibm-provider,
- and, for Aer GPU, CUDA toolkit and minimum driver versions, per OS?
3) For macOS arm64, what is the recommended approach to ensure the OpenMP runtime used by qiskit-aer is bundled or located at runtime without relying on Homebrew? Are there flags or environment variables that Aer honors to find libomp in a relocatable way?
4) For Windows environments, are there prebuilt Aer wheels that avoid a local C++ toolchain entirely for Python 3.12, or documented minimal MSVC build tools when a wheel is not available?
5) For offline/HPC installs:
- Suggested procedure to build a multi-platform wheelhouse that aligns with manylinux baselines on RHEL 8/9 and Ubuntu LTS?
- Any experience using auditwheel/delvewheel to vendor OpenMP or other shared deps into Aer wheels to reduce runtime surprises?
6) Container recommendations:
- Base images known to be compatible with Aer CPU and Aer GPU wheels (e.g., specific CUDA runtime images and glibc baselines) that minimize surprise at import time.
- Known-good Dockerfiles or Apptainer recipes for Python 3.11/3.12 with Aer GPU.
7) Nix/Guix or conda-lock experience:
- Has anyone achieved a fully hermetic Nix flake or conda-lock environment for Terra + Aer (CPU/GPU) + IBM provider across the OS/Python matrix above?
8) QPY compatibility guidance:
- Is there a formal policy for QPY forward/backward compatibility across Terra minor versions, and a recommended practice to assert compatibility during CI?
9) General advice:
- Is the meta-package still recommended, or is it preferable to pin individual components?
- Any published “known good set” (KGS) tags or reference environments maintained by the core team that we can mirror?
If helpful, I can share representative error signatures we hit (e.g., missing libomp on macOS, wheel-not-found for cp312-manylinux on certain platforms, CUDA solver loader failures in containers). The goal is to converge on a minimal set of patterns and artifacts that the community can reuse for deterministic, cross-platform Qiskit deployments, including GPU acceleration and offline installs.