Installation der Qiskit C API

Dieser Leitfaden beschreibt, wie du die Qiskit C API installierst und verwendest. Lies nach Abschluss der Installation Erweitere Python mit der Qiskit C API.

Das folgende Beispiel erstellt ein Observable mit C:

// file: example.c
#include <stdio.h>
#include <stdint.h>
#include <qiskit.h>

int main(int argc, char *argv[]) {
    // build a 100-qubit empty observable
    uint32_t num_qubits = 100;
    QkObs *obs = qk_obs_zero(num_qubits);

    // add the term 2 * (X0 Y1 Z2) to the observable
    QkComplex64 coeff = {2, 0};
    QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; 
    // bit terms: X Y Z
    uint32_t indices[3] = {0, 1, 2};  // indices: 0 1 2
    QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};
    qk_obs_add_term(obs, &term);  // append the term

    // print some properties and the observable itself
    printf("num_qubits: %i\n", qk_obs_num_qubits(obs));
    printf("num_terms: %lu\n", qk_obs_num_terms(obs));
    printf("observable: %s\n", qk_obs_str(obs));

    // free the memory allocated for the observable
    qk_obs_free(obs);

    return 0;
}

UNIX-ähnliche Systeme

Dieser Abschnitt enthält Build-Anweisungen für UNIX-ähnliche Systeme.

Voraussetzungen

Für die Kompilierung sind folgende Tools erforderlich:

• Ein Rust-Compiler: siehe zum Beispiel die Anleitung zur Installation von Qiskit aus dem Quellcode
• Ein C-Compiler: zum Beispiel GCC unter Linux und Clang unter MacOS. Die C API von Qiskit ist kompatibel mit einem Compiler, der dem C11-Standard entspricht.
• cbindgen: ein Tool zur Erstellung des C-Headers, das du mit cargo install cbindgen installieren kannst Das Ausführen des Tools über die Kommandozeile sollte aktiviert sein, was möglicherweise das Exportieren deiner PATH-Variable einschließlich /path/to/.cargo/bin erfordert.
• Installierte Python-Bibliothek (Python 3.9+): Die Python-Bibliothek wird während des dynamischen Linkens benötigt. Beachte, dass Python zur Laufzeit nicht verwendet wird und der Interpreter nie initialisiert wird; nur einige Symbole aus libpython müssen definiert sein. Weitere Details finden sich in diesem Issue.
• (GNU) Make: Dies ist optional, wird aber für automatisierte Installationsprozesse empfohlen.

Dieser Code überprüft, ob alles installiert wurde:

rustc --version
gcc --version
cbindgen --version
make --version  # optional, but recommended

Build

Um den C-Header und die Bibliothek zu erstellen, kannst du folgenden Make-Befehl¹ im Qiskit-Root-Verzeichnis ausführen:

make c

Dies stellt die kompilierte Shared Library in dist/c/lib und den qiskit.h-Header mit allen Funktionsdeklarationen in dist/c/include bereit. Beachte, dass der genaue Bibliotheksname von der Plattform abhängt; zum Beispiel libqiskit.so unter UNIX und libqiskit.dylib unter MacOS. (Beachte, dass dieser Schritt derzeit viele Warnungen ausgibt, was zu erwarten ist und kein Grund zur Besorgnis. Zukünftige Versionen werden die Warnungen entfernen.)

Du kannst dann ein C-Programm unter Verwendung des Qiskit C-Headers und der Bibliothek kompilieren:

gcc example.c -o example.o -I /path/to/dist/c/include -L /path/to/dist/c/lib -lqiskit

Um sicherzustellen, dass die Qiskit-Bibliothek beim Linken gefunden wird, setze den Laufzeit-Bibliothekspfad so, dass er /path/to/dist/c/lib enthält. Wenn die Python-Bibliothek standardmäßig nicht beim dynamischen Linken verfügbar ist, muss dies ebenfalls hinzugefügt werden. Diese Befehle sind plattformabhängig. Unter Linux:

export LD_LIBRARY_PATH=/path/to/dist/c/lib:$LD_LIBRARY_PATH
# On Linux, the Python library is typically included 
# in the dynamic library path by default.
export LD_LIBRARY_PATH=/path/to/python/lib:$LD_LIBRARY_PATH

Unter MacOS:

export DYLD_LIBRARY_PATH=/path/to/dist/c/lib:$DYLD_LIBRARY_PATH
export DYLD_LIBRARY_PATH=/path/to/python/lib:$DYLD_LIBRARY_PATH

Alternativ kannst du den Laufzeit-Bibliothekspfad während der Kompilierung festlegen, indem du

-Wl,-rpath,/path/to/dist/c/lib
# same for Python

zu den Compiler-Flags hinzufügen. Zusätzlich muss die Python-Bibliothek beim dynamischen Linken verfügbar sein. In Linux-Umgebungen ist dies normalerweise standardmäßig der Fall.

Jetzt kannst du die Binärdatei ausführen:

./example.o

was, wenn du das zuvor gezeigte Beispiel-Snippet verwendest, ausgeben sollte:

num_qubits: 100
num_terms: 1
observable: SparseObservable { num_qubits: 100, 
coeffs: [Complex { re: 2.0, im: 0.0 }], 
bit_terms: [X, Y, Z], 
indices: [0, 1, 2], 
boundaries: [0, 3] }

Windows

Dieser Abschnitt enthält Build-Anweisungen für Windows-Systeme.

Es gibt zwei unabhängige Möglichkeiten, die C API unter Windows zu verwenden:

• Erstelle Python-Erweiterungsmodule, die die Qiskit C API verwenden. Folge den Schritten 1-5. Dieser Weg verwendet die C-Header, die mit dem Python-Paket qiskit ausgeliefert werden, und erfordert weder Rust noch cbindgen.

• Erstelle die eigenständige C-Bibliothek, gegen die du von einem reinen C-Programm aus linken kannst, wie im Abschnitt UNIX-ähnlich beschrieben. Schließe Schritt 1 ab und springe dann zu Erstelle die eigenständige Bibliothek, wo die zusätzlichen Anforderungen aufgeführt sind.

Voraussetzungen

• Für einige Schritte sind Administratorrechte erforderlich.

• 5-8 GB freier Speicherplatz.

• Ein C-Compiler: Microsoft Visual C++ (MSVC), installiert in Schritt 1.

• Eine 64-Bit-Python-Installation (3.10 oder höher), installiert in Schritt 1.

Bevor du beginnst

Erstelle deinen Arbeitsbereich. Dies sollte ein kurzer Pfad auf einem lokalen Laufwerk sein. Verwende keine mit OneDrive synchronisierten Ordner (wie Dokumente oder Desktop), Netzlaufwerke oder Pfade mit Leerzeichen oder Nicht-ASCII-Zeichen. Wenn dein Benutzername nicht-englische Zeichen enthält, lege den Arbeitsbereich nicht in deinem Benutzerordner an.

Beispiele für gute Arbeitsbereich-Pfade: C:\workspace, D:\workspace, C:\Users\john\workspace

Schritt 1. Installiere die Voraussetzungen

MSVC-Build-Tools (C-Compiler) — zuerst installieren

Dies ist ein großer Download (2-5 GB, 10-30 Min.). Installiere ihn zuerst, damit du sofort weißt, ob dein Computer kompatibel ist.

hinweis

Requires administrator rights.

Option A — winget Öffne ein PowerShell-Terminal und führe Folgendes aus:

winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive --wait"

Das Terminal wirkt eingefroren, während der Installer läuft. Das ist normal und dauert 10-30 Minuten. Achte in der Taskleiste auf ein Fenster „Visual Studio Installer".

Wenn winget nicht erkannt wird, aktualisiere den App Installer über den Microsoft Store, oder verwende Option B.

Option B — manueller Download Öffne die Website Visual Studio Build Tools for C++ und klicke auf Download Build Tools. Führe die ausführbare Datei aus, um die Installation zu starten.

Wenn sich das Fenster „Installing Visual Studio" öffnet, wähle auf der Registerkarte Workloads „Desktop development with C++". Weitere Details findest du auf der Seite Install C and C++ support in Visual Studio.

VS Code

Lade VS Code von der Website Visual Studio Code herunter oder führe winget install Microsoft.VisualStudio.Code aus. Führe die heruntergeladene ausführbare Datei aus, um VS Code zu installieren.

Fahre nach der Installation mit diesen Schritten fort:

1. Öffne VS Code
2. Klicke auf File → Open Folder und wähle dann deinen Arbeitsbereich aus (zum Beispiel C:\workspace).
3. Klicke auf Terminal → New terminal, um ein PowerShell-Terminal zu öffnen.
4. Klicke links auf das Extensions-Symbol oder drücke Strg+Umschalt+X. Suche im Extensions-Fenster nach ms-python.python, ms-toolsai.jupyter und ms-vscode.cpptools und installiere sie.

Führe die restlichen Befehle in dieser Anleitung im VS Code-Terminal aus, sofern nicht anders angegeben. Das VS Code-Terminal verwendet standardmäßig PowerShell; so vermeidest du Verwechslungen mit der integrierten Windows-Eingabeaufforderung.

Lege die Arbeitsbereich-Variable fest. Wenn dein Arbeitsbereich zum Beispiel workspace heißt, führe Folgendes aus:

$WORKSPACE = "C:\workspace"   # change to your workspace path
mkdir $WORKSPACE -Force
cd $WORKSPACE

Python 3.12 (empfohlene Version)

Python 3.12 wird empfohlen, da es die beste Wheel-Verfügbarkeit für qiskit-aer und andere Abhängigkeiten bietet. 3.10 und 3.11 funktionieren ebenfalls, aber bei 3.13 oder höher fehlen für manche Pakete möglicherweise vorgefertigte Wheels.

Öffne das VS Code-Terminal und führe den folgenden Code aus, um eine geeignete Python-Version zu ermitteln:

# ── Pre-checks ───────────────────────────────────────────────────────────────
if ($env:CONDA_DEFAULT_ENV -or $env:CONDA_PREFIX) {
    Write-Warning "Conda is active. Run 'conda deactivate' first, or open a new terminal."
    return
}
if ($env:VIRTUAL_ENV) {
    Write-Warning "A virtual environment is active: $env:VIRTUAL_ENV — run 'deactivate' first."
    return
}

# ── Detect Python ────────────────────────────────────────────────────────────
$PYTHON_EXE = $null
try {
    $ver  = (py -3 --version 2>&1) -replace "Python ", ""
    $bits = py -3 -c "import platform; print(platform.architecture()[0])"
    $path = py -3 -c "import sys; print(sys.executable)"
    if ($path -match "(?i)(anaconda|miniconda|miniforge|mambaforge|[/\\]conda[/\\]|[/\\]envs[/\\])") {
        Write-Host "Skipping conda-managed Python at: $path"
    } elseif ([version]$ver -ge [version]"3.10" -and $bits -eq "64bit") {
        $PYTHON_EXE = $path
        Write-Host "Python $ver (64-bit) found: $PYTHON_EXE"
    } else {
        Write-Host "Skipping ($ver, $bits) — need 3.10+ 64-bit"
    }
} catch {}
if (-not $PYTHON_EXE) {
    try {
        $ver  = (python --version 2>&1) -replace "Python ", ""
        $bits = python -c "import platform; print(platform.architecture()[0])"
        $path = python -c "import sys; print(sys.executable)"
        if ($path -match "(?i)(anaconda|miniconda|miniforge|mambaforge|[/\\]conda[/\\]|[/\\]envs[/\\])") {
            Write-Host "Skipping conda-managed Python at: $path"
        } elseif ([version]$ver -ge [version]"3.10" -and $bits -eq "64bit") {
            $PYTHON_EXE = $path
            Write-Host "Python $ver (64-bit) found: $PYTHON_EXE"
        } else {
            Write-Host "Skipping ($ver, $bits) — need 3.10+ 64-bit"
        }
    } catch {}
}

# Install Python 3.12 if it wasn't found.
if (-not $PYTHON_EXE) {
    Write-Host "Not found. Installing Python 3.12..."
    winget install Python.Python.3.12
    Write-Host "Close and reopen the terminal, then rerun this snippet."
}
if ($PYTHON_EXE -and ($PYTHON_EXE -match '[^\x20-\x7E]')) {
    Write-Warning "Python path has non-ASCII characters. Keep your workspace on an ASCII path."
}
if ($PYTHON_EXE) { Write-Host "`$PYTHON_EXE = '$PYTHON_EXE'" }

Wenn der Download nicht funktioniert hat oder du den manuellen Download bevorzugst, kommentiere die Codezeilen aus, die Python 3.12 installieren, und lade Python 3.12 dann von der Python-Website herunter. Führe die ausführbare Datei aus, um Python zu installieren. Wähle während der Installation „Add Python to PATH" aus und führe dann das obige Snippet erneut aus, um sicherzustellen, dass es gefunden wird.

Hinweise

• Verwende NICHT das Python aus dem Microsoft Store, da ihm C-Header fehlen. Wenn python den Microsoft Store öffnet, deaktiviere den Alias unter Windows-Einstellungen → Apps → Erweiterte App-Einstellungen → App-Ausführungsaliase.

• Anaconda-Nutzer: Führe conda deactivate aus, bis das Präfix (base) verschwindet. Wenn es nicht verschwindet, öffne ein neues Terminal in VS Code.

Git (optional)

Nur erforderlich, wenn du Lab-Repositorys klonst. Führe winget install Git.Git aus.

Schritt 2 - Richte die virtuelle Python-Umgebung mit Qiskit ein

VS Code-Terminal zurücksetzen

Öffne das VS Code-Terminal und setze es zurück:

$WORKSPACE = "C:\workspace"   # change to your workspace path
if (-not $PYTHON_EXE) {
    if (Get-Command py -ErrorAction SilentlyContinue) { $PYTHON_EXE = py -3 -c "import sys; print(sys.executable)" }
    elseif (Get-Command python -ErrorAction SilentlyContinue) { $PYTHON_EXE = python -c "import sys; print(sys.executable)" }
    else { Write-Host "Python not found — complete Step 1.3 first." ; return }
    Write-Host "`$PYTHON_EXE = '$PYTHON_EXE'"
}

Virtuelle Umgebung erstellen und aktivieren

Erlaube die Skriptausführung (einmal pro Benutzer) und erstelle dann die virtuelle Umgebung:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
cd $WORKSPACE
& $PYTHON_EXE -m venv .venv --prompt workspace
.\.venv\Scripts\Activate.ps1

Wenn bei der Aktivierung ein roter Fehler zu „scripts disabled" angezeigt wird, wurde die Zeile Set-ExecutionPolicy nicht ausgeführt. Führe sie manuell aus und versuche es erneut.

Deine Eingabeaufforderung sollte jetzt (workspace) anzeigen.

Überprüfe:

Get-Command python | Select-Object -First 1 -ExpandProperty Source
# → workspace\.venv\Scripts\python.exe

Pakete installieren

python -m pip install --upgrade pip setuptools wheel
pip install "qiskit[visualization]>=2.4.2"
pip install --prefer-binary qiskit-ibm-runtime qiskit-aer
pip install notebook ipykernel ipywidgets  # optional: run the following Python steps in Jupyter

--prefer-binary vermeidet das Kompilieren von qiskit-aer aus dem Quellcode. Wenn qiskit-aer weiterhin fehlschlägt, versuche pip install qiskit-aer --only-binary=:all: oder überspringe es. qiskit-aer ist optional und wird nur für die lokale Simulation benötigt.

hinweis

Führe NICHT pip install --upgrade qiskit nach der Einrichtung aus. Ein Upgrade auf eine neue Minor-Version macht C-Erweiterungen, die gegen die alte Version erstellt wurden, unbrauchbar.

Schritt 3 - Lade die MSVC-Umgebung

Führe den folgenden Code in jeder neuen Python-Sitzung aus (zum Beispiel jedes Mal, wenn du einen Jupyter-Kernel neu startest). Er findet und lädt die MSVC-Entwicklungsumgebung automatisch, sodass du die integrierte x64-Eingabeaufforderung nicht benötigst.

Das Beispiel in dieser Dokumentation erstellt C-Erweiterungsmodule mit setuptools und MSVC. Im Allgemeinen definierst du QISKIT_PYTHON_EXTENSION, bindest qiskit.h ein und rufst qk_import() in deiner Init-Funktion auf. Zur Build-Zeit werden nur Header aus qiskit.capi.get_include() benötigt — es wird keine Bibliothek gelinkt. Details findest du unter Qiskit in Python mit C erweitern.

MSVC-Umgebung laden

import os, sys, subprocess, glob, shutil

def load_msvc_env():
    if os.name != "nt":
        return "Not Windows — the system C compiler is used as-is."
    if shutil.which("cl"):
        return "cl.exe is already available in this kernel."

    pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
    pf = os.environ.get("ProgramFiles", r"C:\Program Files")
    vcvars = None

    vswhere = os.path.join(pf86, "Microsoft Visual Studio", "Installer", "vswhere.exe")
    if os.path.isfile(vswhere):
        # vswhere outputs UTF-8 regardless of system locale
        inst = subprocess.run(
            [vswhere, "-latest", "-products", "*",
             "-requires", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
             "-property", "installationPath"],
            capture_output=True, text=True, encoding="utf-8").stdout.strip()
        if inst:
            cand = os.path.join(inst, "VC", "Auxiliary", "Build", "vcvars64.bat")
            if os.path.isfile(cand):
                vcvars = cand

    if not vcvars:
        pat = os.path.join("Microsoft Visual Studio", "*", "*",
                           "VC", "Auxiliary", "Build", "vcvars64.bat")
        hits = glob.glob(os.path.join(pf86, pat)) + glob.glob(os.path.join(pf, pat))
        if hits:
            vcvars = sorted(hits)[-1]

    if not vcvars:
        return ("Could not find vcvars64.bat. Install MSVC Build Tools (Step 1.3), "
                "or launch Jupyter from the x64 Native Tools Command Prompt.")

    # cmd.exe outputs in the OEM codepage (cp437/cp850/etc.), not the ANSI codepage
    out = subprocess.run(f'"{vcvars}" >nul 2>&1 && set',
                         capture_output=True, text=True, encoding="oem", shell=True).stdout
    for line in out.splitlines():
        if "=" in line:
            k, _, v = line.partition("=")
            os.environ[k] = v

    return ("Loaded MSVC from:\n  " + vcvars) if shutil.which("cl") \
        else "Ran vcvars64.bat but cl.exe is still not found — check your MSVC install."

print(load_msvc_env())
print("cl.exe on PATH:", shutil.which("cl") is not None)

Einrichtung überprüfen

Überprüfe, ob die Einrichtung funktioniert hat:

import importlib.util, shutil

checks = {
    "setuptools": importlib.util.find_spec("setuptools") is not None,
    "wheel":      importlib.util.find_spec("wheel") is not None,
    "cl.exe":     shutil.which("cl") is not None,
}
for name, ok in checks.items():
    print(f"  [{'PASS' if ok else 'FAIL':>4}] {name}")

if not checks["cl.exe"]:
    print("\n  cl.exe is not on PATH. rerun the cell above to load the MSVC environment.")
elif all(checks.values()):
    print("\n  Toolchain ready. Continue to the smoke test.")

Schritt 4 - Smoke-Test: Erstelle eine C-Erweiterung

Führe den folgenden Code aus. Er schreibt Quelldateien nach _smoke_pkg/, erstellt eine C-Erweiterung gegen die Qiskit C API und importiert das Ergebnis. Wenn „SMOKE TEST PASSED" ausgegeben wird, ist deine Toolchain bereit.

Das Paket folgt dem Prozess Qiskit in Python mit C erweitern und verwendet Funktionen aus der Qiskit C API-Referenz.

Smoke-Test-Code

import sys, subprocess, pathlib, importlib

root = pathlib.Path("_smoke_pkg")
pkg = root / "src" / "qgss_smoke"
pkg.mkdir(parents=True, exist_ok=True)

(root / "pyworkspace.toml").write_text("""
[build-system]
requires = ["setuptools", "qiskit>=2.4.2"]
build-backend = "setuptools.build_meta"

[workspace]
name = "qgss_smoke"
version = "0.0.1"
dependencies = ["qiskit>=2.4.2"]

[tool.setuptools]
package-dir = {"" = "src"}
""".lstrip())

(root / "setup.py").write_text("""
import qiskit
from setuptools import setup, Extension

core_ext = Extension(
    name="qgss_smoke._core",
    sources=["src/qgss_smoke/_coremodule.c"],
    include_dirs=[qiskit.capi.get_include()],
)
setup(ext_modules=[core_ext])
""".lstrip())

(pkg / "__init__.py").write_text("from . import _core\nbuild_demo = _core.build_demo\n")

(pkg / "_coremodule.c").write_text("""
#define QISKIT_PYTHON_EXTENSION
#include <Python.h>
#include <qiskit.h>
#include <stdint.h>

static PyObject *build_demo(PyObject *self, PyObject *args) {
    QkCircuit *qc = qk_circuit_new(2, 0);
    uint32_t q0[1] = {0};
    qk_circuit_gate(qc, QkGate_H, q0, NULL);
    uint32_t q1[1] = {1};
    qk_circuit_gate(qc, QkGate_X, q1, NULL);
    return qk_circuit_to_python_full(qc);
}

static PyMethodDef core_methods[] = {
    {"build_demo", build_demo, METH_NOARGS, "Build a 2-qubit demo circuit in C."},
    {NULL, NULL, 0, NULL},
};
static struct PyModuleDef core_module = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "_core",
    .m_methods = core_methods,
};
PyMODINIT_FUNC PyInit__core(void) {
    if (qk_import() < 0) {
        return NULL;
    }
    return PyModuleDef_Init(&core_module);
}
""".lstrip())

# On Windows, an imported .pyd is file-locked by the OS. Drop the module from
# sys.modules BEFORE pip install --force-reinstall, otherwise pip fails with
# WinError 32 ("file in use") trying to overwrite the locked .pyd.
if "qgss_smoke._core" in sys.modules:
    del sys.modules["qgss_smoke._core"]
if "qgss_smoke" in sys.modules:
    del sys.modules["qgss_smoke"]

r = subprocess.run(
    [sys.executable, "-m", "pip", "install", "--no-build-isolation",
     "--force-reinstall", "--quiet", str(root.resolve())],
    capture_output=True, text=True,
)
if r.returncode != 0:
    output = (r.stderr + r.stdout).strip()
    print("BUILD FAILED:\n")
    print(output)
    if "WinError 32" in output or "being used by another process" in output:
        print("\n--- TIP ---")
        print("The .pyd file is locked because it was previously imported in this kernel.")
        print("Restart the kernel (Ctrl+Shift+P → 'Jupyter: Restart Kernel'), then rerun")
        print("the Step 3 MSVC cell first, then this cell again.")
    elif "cl.exe" in output.lower() or "vcvars" in output.lower() or "cannot find" in output.lower():
        print("\n--- TIP ---")
        print("The compiler was not found. rerun the Step 3 cell to load the MSVC environment.")
else:
    importlib.invalidate_caches()
    import qgss_smoke
    from qiskit import QuantumCircuit

    qc = qgss_smoke.build_demo()
    ops = dict(qc.count_ops())
    ok = isinstance(qc, QuantumCircuit) and ops.get("h") == 1 and ops.get("x") == 1

    print("Returned object is a QuantumCircuit:", isinstance(qc, QuantumCircuit))
    print("Gates built in C:", ops)
    print("\nSMOKE TEST PASSED — your Windows toolchain can build Qiskit C extensions."
          if ok else "\nSomething is off — check the gates above.")

Schritt 5 — VS Code konfigurieren (optional)

Für mehr Komfort kannst du diesem Prozess folgen, um IntelliSense für C-Dateien einzurichten und den Python-Interpreter automatisch auswählen zu lassen.

Erstelle das Verzeichnis .vscode

Führe im VS Code-Terminal den folgenden Code aus:

mkdir $WORKSPACE\.vscode -Force

Erstelle die Einstellungsdatei

Erstelle .vscode/settings.json in deinem Arbeitsbereich, indem du diesen Code ausführst:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "python.terminal.activateEnvironment": true,
    "jupyter.notebookFileRoot": "${workspaceFolder}"
}

Erstelle die Properties-Datei

Der folgende Code gibt das JSON aus, das du in .vscode/c_cpp_properties.json einfügen musst:

import qiskit.capi

inc = qiskit.capi.get_include().replace("\\", "/")
print(".vscode/c_cpp_properties.json — create this file with the content below:\n")
print('{')
print('    "version": 4,')
print('    "configurations": [')
print('        {')
print('            "name": "Win32",')
print(f'            "includePath": ["{inc}"],')
print('            "defines": ["QISKIT_PYTHON_EXTENSION"],')
print('            "compilerPath": "cl.exe",')
print('            "cStandard": "c11",')
print('            "intelliSenseMode": "windows-msvc-x64"')
print('        }')
print('    ]')
print('}')

Erstelle die VS Code-Erweiterungsdatei

Erstelle in VS Code .vscode/extensions.json mit folgendem Inhalt:

{
    "recommendations": ["ms-python.python", "ms-toolsai.jupyter", "ms-vscode.cpptools"]
}

Erstelle die eigenständige Bibliothek

In diesem Abschnitt wird die eigenständige C-Bibliothek erstellt, die nur benötigt wird, wenn du reine C-Programme kompilieren und linken möchtest, wie im Abschnitt UNIX-ähnlich beschrieben. Zusätzlich zu den Voraussetzungen aus Schritt 1 sind dafür folgende Tools erforderlich:

• Ein Rust-Compiler: siehe zum Beispiel die Anleitung zur Installation von Qiskit aus dem Quellcode

• cbindgen: ein Tool zum Erstellen des C-Headers, das du mit cargo install cbindgen installieren kannst. Das Ausführen des Tools über die Kommandozeile sollte aktiviert sein, wofür du möglicherweise deine PATH-Variable aktualisieren musst, um den Cargo-Pfad einzuschließen.

• Eine Python-Installation mit Zugriff auf sowohl python3.lib als auch python3.dll

• Ein Klon des Qiskit-Repositorys (git clone https://github.com/Qiskit/qiskit.git)

Die eigenständige Bibliothek erstellen

Erstelle zunächst die dynamische Bibliothek qiskit_cext, indem du im VS Code (PowerShell) Terminal im Qiskit-Stammverzeichnis Folgendes ausführst:

$env:PATH = "\path\to\pythonlib;" + $env:PATH
cargo rustc --release --crate-type cdylib -p qiskit-cext

Dadurch wird die dynamische Bibliothek .dll sowie die zugehörige Datei .dll.lib in target/release erzeugt. Erstelle als Nächstes den Header mit

cbindgen --crate qiskit-cext --output dist\c\include\qiskit.h

Dies schreibt den MSVC-kompatiblen Header in dist\c\include.

Jetzt kannst du cl verwenden, um das C-Programm zu kompilieren. Um sicherzustellen, dass der Compiler die Qiskit-Bibliothek findet, füge target\release zur PATH-Variable hinzu.

$env:PATH = "\path\to\target\release;" + $env:PATH
cl example.c qiskit_cext.dll.lib -I\path\to\dist\c\include

Füge vor dem Ausführen den Pfad zu deiner python3.dll hinzu.

$env:PATH = "\path\to\python3-dll;" + $env:PATH
.\example.exe

sollte dann ausgeben:

num_qubits: 100
num_terms: 1
observable: SparseObservable { num_qubits: 100, 
coeffs: [Complex { re: 2.0, im: 0.0 }], 
bit_terms: [X, Y, Z], 
indices: [0, 1, 2], 
boundaries: [0, 3] }

Fehlerbehebung

winget wird nicht erkannt

Aktualisiere den App Installer über den Microsoft Store, oder verwende die entsprechenden manuellen Download-Links

cl wird nicht erkannt

Führe die MSVC-Ladezelle (Schritt 3) erneut aus, oder verwende die x64 Native Tools Command Prompt

python öffnet den Microsoft Store

Gehe zu Einstellungen → Apps → Erweiterte App-Einstellungen → App-Ausführungsaliase und deaktiviere python.exe

.ps1 cannot be loaded / Skripte deaktiviert

Führe Set-ExecutionPolicy -Scope CurrentUser RemoteSigned aus und versuche es erneut

cannot open file 'qiskit.h'

Führe python -c "import qiskit.capi; print(qiskit.capi.get_include())" aus und bestätige, dass der Pfad existiert

qiskit.capi nicht gefunden

Führe pip install "qiskit[visualization]~=2.4.2" aus

qiskit-aer-Build schlägt fehl

Führe pip install qiskit-aer --only-binary=:all: aus. Falls das auch fehlschlägt, verwende Python 3.12 oder überspringe aer, das optional ist

Build läuft, aber der Import schlägt mit einem Versionsfehler fehl

Die erstellte Qiskit-C-Erweiterung und die installierte Qiskit-Version müssen dieselbe Version haben. Installiere Qiskit mit pip install "qiskit~=2.4.2" neu

Ich habe das C neu erstellt, aber der Schaltkreis hat sich nicht geändert

Eine C-Erweiterung kann nicht live neu importiert werden. Starte den Kernel neu, führe die MSVC-Befehle (Schritt 3) erneut aus und erstelle dann neu

PowerShell-Skript wurde blockiert

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Fehler durch Pfadlänge

Verwende einen kurzen Root-Pfad auf C:\ (zum Beispiel C:\workspace, oder den Pfad, den du im Einrichtungsschritt festgelegt hast), oder aktiviere Long Paths: Einstellungen → System → Für Entwickler → Long Paths

Conda ist aktiv (die Eingabeaufforderung zeigt (base)) oder Builds verhalten sich nach der Nutzung von Anaconda merkwürdig

Führe conda deactivate aus, bis CONDA_DEFAULT_ENV und CONDA_PREFIX beide aus der Umgebung verschwunden sind. Prüfe mit $env:CONDA_PREFIX. Falls sie bestehen bleiben, öffne eine neue PowerShell (keine Anaconda-Eingabeaufforderung) und versuche es erneut ab Schritt 2.

Die virtuelle Umgebung wurde aus einem conda-verwalteten Python erstellt (prüfe die Zeile home = in .venv\pyvenv.cfg)

Die virtuelle Umgebung hat die C-Laufzeit von conda geerbt und kann nicht direkt behoben werden. Lösche sie, lade Python 3.12 von der Python-Website herunter und erstelle sie neu. Führe Remove-Item -Recurse -Force .venv aus, führe dann das Python-Erkennungs-Snippet aus Schritt 1 erneut aus, um $PYTHON_EXE festzulegen, und erstelle anschließend die virtuelle Umgebung neu (Schritt 2).

DLL load failed beim Import

Wahrscheinlich sickert conda in die virtuelle Umgebung ein. Prüfe die beiden Punkte direkt darüber. Bestätige außerdem, dass Python 64-Bit ist: python -c "import platform; print(platform.architecture())"

Build schlägt mit verstümmelten Pfaden oder C1083 fehl

Dein Benutzername oder Arbeitsbereich-Pfad enthält Nicht-ASCII-Zeichen. Verschiebe den Arbeitsbereich an einen kurzen, reinen ASCII-Pfad (zum Beispiel C:\workspace)

Build oder Import schlägt zufällig fehl, funktioniert aber bei erneutem Versuch

Der Arbeitsbereich-Ordner wird von OneDrive synchronisiert. Verschiebe ihn an einen lokalen Pfad wie C:\workspace

Build wurde mittendrin unterbrochen (zum Beispiel durch einen Stromausfall)

Lösche den Ordner _smoke_pkg in deinem Arbeitsbereich, führe die MSVC-Ladezelle erneut aus und führe dann die Smoke-Test-Zelle erneut aus

pip install schlägt mit einem SSL-Zertifikatsfehler fehl

Dein Netzwerk verwendet einen Proxy, der HTTPS abfängt. Versuche pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit auszuführen oder bitte deinen Netzwerkadministrator um das Proxy-CA-Zertifikat

Windows Defender stellt die .pyd-Datei unter Quarantäne

Füge die Ordner .venv und _smoke_pkg deines Arbeitsbereichs zu den Defender-Ausnahmen hinzu, indem du zu Windows-Sicherheit → Viren- & Bedrohungsschutz → Einstellungen verwalten → Ausschlüsse gehst

VS Build Tools können nicht installiert werden (keine Administratorrechte)

Administratorzugriff ist erforderlich. Bitte deine IT-Abteilung um Zugriff

WinError 32 / Datei wird beim Neuerstellen verwendet

Die .pyd-Datei ist durch den laufenden Kernel gesperrt. Starte den Kernel neu (Strg+Umschalt+P → Jupyter: Restart Kernel), führe Schritt 3 erneut aus und erstelle dann neu

Befehle tun stillschweigend nichts (kein Fehler, keine Ausgabe)

Du befindest dich möglicherweise in cmd.exe statt in PowerShell. Prüfe deine Eingabeaufforderung: PowerShell zeigt PS C:\>, cmd zeigt C:\>. Öffne PowerShell über das Startmenü oder Win+X

MSVC-Installation scheint hängen zu bleiben

Die Flags --passive --wait blockieren PowerShell, während der Installer im Hintergrund läuft. Achte in deiner Taskleiste auf ein Fenster „Visual Studio Installer". Die Installation kann 10-30 Minuten dauern

Nächste Schritte

Empfehlungen

• Erfahre, wie du Python mit der Qiskit C API erweiterst.
• Installiere Qiskit.
• Entdecke die Qiskit C API-Referenz.

Footnotes

1. Wenn du Make nicht installiert hast, überprüfe das Makefile im Qiskit-Root-Verzeichnis für die erforderlichen Befehle - oder installiere einfach Make; es ist noch nicht zu spät. ↩