Troubleshooting

pip can't find psiqdk

PsiQDK requires Python 3.11, 3.12, or 3.13. Check your Python version:

python --version

Note

If python --version shows an incompatiable python different version, install a supported Python version and make sure your environment is using it. See the Python packaging guide on managing Python versions ⧉ for setup help.

If your Python version is supported, the next most likely cause is an unsupported platform. PsiQDK ships platform-specific wheels for:

• macOS (universal2: Apple Silicon and Intel)
• Linux x86_64 (glibc, via manylinux)
• Linux x86_64 (musl libc, via musllinux)

Windows is not supported; run PsiQDK inside WSL ⧉ on a supported Linux distribution. Other architectures (e.g. Linux ARM) are not currently supported.

psiqdk reports a dependency mismatch

Something else in your environment has pinned a different version of one of the bundled components. Common causes are a downstream project requiring an older version, or a stale virtualenv that has drifted from the PsiQDK. A mismatch looks like this:

$ psiqdk
psiqdk version: 2.0.0
Python: 3.12.1 (darwin)

Main dependencies:
  ✓ bartiq                         installed=0.16.1       spec===0.16.1
  ✗ psiqdk-algorithms              installed=1.12.0       spec===1.19.2
  ✓ psiqdk-visualize               installed=0.97.1       spec===0.97.1
  ✓ psiqdk-workbench               installed=4.44.0       spec===4.44.0
  ✓ qref                           installed=0.11.0       spec===0.11.0

✗ 1 dependency issue(s):
  - psiqdk-algorithms: MISMATCH — expected ==1.19.2, got 1.12.0

This can be fixed by reinstalling the psiqdk with this command:

pip install --upgrade --force-reinstall psiqdk

Run psiqdk again to confirm all checks pass.

If the mismatch persists, another package in your environment is holding back the bundled component. Find the culprit:

pip show psiqdk-algorithms

The Required-by: line lists every package that depends on psiqdk-algorithms. Upgrade or remove the package that's pinning the older version, or start fresh in a clean virtualenv:

python -m venv .venv
source .venv/bin/activate
pip install psiqdk
psiqdk

ImportError after a clean install

If you see ImportError immediately on import psiqdk.workbench (or another component), the most common cause is an incompatiable Python version. Workbench's native extensions are not built for older Pythons. Upgrade your interpreter and reinstall in a fresh virtualenv.

Getting help

Open an issue on the PsiQDK GitHub repository ⧉ with the output of psiqdk attached.