Skip to content

Troubleshooting

pip can't find psiqdk

PsiQDK requires Python 3.11 or newer. Check your Python version:

python --version

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 --verify reports a 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 pins.

A mismatched run looks like this:

$ psiqdk --verify
Verifying PsiQDK dependencies...
----------------------------------------------------------------------
Main dependencies:
  ✓ bartiq             (installed: 0.16.1)
  ✗ psiqdk-algorithms  (installed: 1.12.0)
      MISMATCH - version 1.12.0 does not satisfy ==1.14.0
  ✓ psiqdk-visualize   (installed: 0.94.1)
  ✓ psiqdk-workbench   (installed: 4.41.1)
  ✓ qref               (installed: 0.11.0)
----------------------------------------------------------------------
✗ Some dependencies have issues

To fix dependency issues:
  pip install --upgrade --force-reinstall psiqdk

The simplest fix is the suggested command:

pip install --upgrade --force-reinstall psiqdk

This re-resolves every bundled package against PsiQDK's pinned set. Run psiqdk --verify 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 --verify

ImportError after a clean install

If you see ImportError immediately on import psiqdk.workbench (or another component), the most common cause is a Python version below 3.11. 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 --version attached. For commercial support, contact PsiQuantum through your organization's designated channel.