Instalar a API C do Qiskit

Este guia descreve como instalar e usar a API C do Qiskit. Após a instalação estar concluída, leia Estender Python com a API C do Qiskit.

O exemplo a seguir constrói um observable com 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-like

Esta seção fornece instruções de compilação para sistemas do tipo UNIX.

Requisitos

A compilação requer as seguintes ferramentas:

• Um compilador Rust: veja, por exemplo, o guia de instalação do Qiskit a partir do código-fonte
• Um compilador C: por exemplo, GCC no Linux e Clang no MacOS. A API C do Qiskit é compatível com compiladores que seguem o padrão C11.
• cbindgen: uma ferramenta para criar o cabeçalho C, que você pode instalar com cargo install cbindgen Executar a ferramenta pela linha de comando deve estar habilitado, o que pode exigir a exportação da variável PATH para incluir /path/to/.cargo/bin.
• Biblioteca Python instalada (Python 3.9+): a biblioteca Python é necessária durante a vinculação dinâmica. Note que o Python não é usado em tempo de execução e o interpretador nunca é inicializado; apenas alguns símbolos de libpython precisam estar definidos. Veja esta issue para mais detalhes.
• (GNU) Make: opcional, mas recomendado para usar processos de instalação automatizados.

Este código verifica que tudo foi instalado corretamente:

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

Compilação

Para compilar o cabeçalho C e a biblioteca, você pode executar o seguinte comando Make¹ na raiz do Qiskit,

make c

o que fornecerá a biblioteca compartilhada compilada em dist/c/lib e o cabeçalho qiskit.h com todas as declarações de funções em dist/c/include. Note que o nome exato da biblioteca depende da plataforma; por exemplo, libqiskit.so no UNIX e libqiskit.dylib no MacOS. (Note que esta etapa atualmente emite muitos avisos, o que é esperado e não é motivo de preocupação. Versões futuras removerão os avisos.)

Você pode então compilar um programa C usando o cabeçalho e a biblioteca C do Qiskit:

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

Para garantir que a biblioteca do Qiskit seja encontrada durante a vinculação, defina o caminho da biblioteca em tempo de execução para incluir /path/to/dist/c/lib. Se a biblioteca Python não estiver disponível por padrão durante a vinculação dinâmica, ela também precisará ser adicionada. Esses comandos dependem da plataforma. No 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

No MacOS:

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

Como alternativa, você pode definir o caminho da biblioteca em tempo de execução durante a compilação adicionando

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

aos flags do compilador. Além disso, a biblioteca Python precisa estar disponível durante a vinculação dinâmica. Em ambientes Linux, isso normalmente é o padrão.

Agora você pode executar o binário:

./example.o

que, se usar o trecho de exemplo mostrado anteriormente, deve imprimir

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

Esta seção fornece instruções de compilação para sistemas Windows.

Existem duas formas independentes de usar a API C no Windows:

• Compile módulos de extensão Python que usam a API C do Qiskit. Siga as etapas 1-5. Esse caminho usa os cabeçalhos C fornecidos com o pacote Python qiskit e não requer Rust nem cbindgen.

• Compile a biblioteca C independente para vincular a um programa C puro, como é feito na seção do tipo UNIX. Complete a etapa 1 e depois pule para Compilar a biblioteca independente, que lista seus requisitos adicionais.

Requisitos

• São necessários direitos de administrador para algumas etapas.

• 5-8 GB de espaço livre em disco.

• Um compilador C: Microsoft Visual C++ (MSVC), instalado na etapa 1.

• Uma instalação do Python de 64 bits (3.10 ou posterior), instalada na etapa 1.

Antes de começar

Crie seu espaço de trabalho. Este deve ser um caminho curto em uma unidade local. Não use pastas sincronizadas com o OneDrive (como Documents ou Desktop), unidades de rede, ou caminhos com espaços ou caracteres não ASCII. Se seu nome de usuário contiver caracteres não ingleses, não o coloque dentro da sua pasta de usuário.

Exemplos de bons caminhos de espaço de trabalho: C:\workspace, D:\workspace, C:\Users\john\workspace

Etapa 1. Instale os pré-requisitos

MSVC Build Tools (compilador C) — instale isso primeiro

Este é um download grande (2-5 GB, 10-30 min). Instale-o primeiro para saber imediatamente se seu computador é compatível.

nota

Requires administrator rights.

Opção A — winget Abra um terminal do PowerShell e execute o seguinte:

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

O terminal parece congelado enquanto o instalador é executado. Isso é normal e levará de 10 a 30 minutos. Procure na barra de tarefas uma janela "Visual Studio Installer".

Se winget não for reconhecido, atualize o App Installer na Microsoft Store, ou use a Opção B.

Opção B — download manual Abra o site Visual Studio Build Tools for C++ e clique em Download Build Tools. Execute o executável para iniciar a instalação.

Quando a janela Installing Visual Studio abrir, na aba Workloads, escolha "Desktop development with C++". Consulte a página Install C and C++ support in Visual Studio para mais detalhes.

VS Code

Baixe o VS Code no site Visual Studio Code, ou execute winget install Microsoft.VisualStudio.Code. Execute o arquivo executável baixado para instalar o VS Code.

Depois de instalado, continue com as seguintes etapas:

1. Abra o VS Code
2. Clique em File → Open Folder e selecione seu espaço de trabalho (por exemplo, C:\workspace).
3. Clique em Terminal → New terminal para abrir um terminal do PowerShell.
4. Clique no ícone Extensions à esquerda ou pressione Ctrl+Shift+X. Na janela Extensions, pesquise e instale ms-python.python, ms-toolsai.jupyter e ms-vscode.cpptools.

Execute o restante dos comandos deste guia no terminal do VS Code, a menos que seja instruído de outra forma. O terminal do VS Code usa PowerShell por padrão, evitando confusões com o prompt de comando embutido do Windows.

Defina a variável de espaço de trabalho. Por exemplo, se seu espaço de trabalho for chamado workspace, execute o seguinte:

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

Python 3.12 (versão recomendada)

O Python 3.12 é recomendado porque tem a melhor disponibilidade de wheels para qiskit-aer e outras dependências. 3.10 e 3.11 também funcionam, mas 3.13 ou posterior podem não ter wheels pré-compilados para alguns pacotes.

Abra o terminal do VS Code e execute o seguinte código para detectar uma versão adequada do Python:

# ── 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'" }

Se o download não funcionou, ou se você preferir o download manual, comente as linhas de código que instalam o Python 3.12, depois baixe o Python 3.12 no site Python. Execute o executável para instalar o Python. Selecione "Add Python to PATH" durante a instalação, depois execute novamente o snippet acima para garantir que ele está sendo encontrado.

Notas

• NÃO use o Python da Microsoft Store porque ele não possui os cabeçalhos C. Se python abrir a Microsoft Store, desative o alias indo em Windows Settings → Apps → Advanced app settings → App execution aliases.

• Usuários do Anaconda: execute conda deactivate até que o prefixo (base) desapareça. Se ele não desaparecer, abra um novo terminal no VS Code.

Git (opcional)

Necessário apenas se você clonar repositórios de laboratório. Execute winget install Git.Git.

Etapa 2 - Configure o ambiente virtual Python com o Qiskit

Redefina o terminal do VS Code

Abra o terminal do VS Code e redefina-o:

$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'"
}

Crie e ative um ambiente virtual

Permita a execução de scripts (uma vez por usuário), depois crie o ambiente virtual:

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

Se a ativação mostrar um erro vermelho sobre "scripts disabled", a linha Set-ExecutionPolicy não foi executada. Execute-a manualmente e tente novamente.

Seu prompt agora deve mostrar (workspace).

Verify:

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

Instale os pacotes

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 evita compilar qiskit-aer a partir do código-fonte. Se qiskit-aer ainda falhar, tente pip install qiskit-aer --only-binary=:all: ou pule essa etapa. qiskit-aer é opcional e só é necessário para simulação local.

nota

NÃO execute pip install --upgrade qiskit após a configuração. Atualizar para uma nova versão secundária quebra as extensões C compiladas contra a versão antiga.

Etapa 3 - Carregue o ambiente MSVC

Execute o seguinte código em cada nova sessão do Python (por exemplo, toda vez que reiniciar um kernel do Jupyter). Ele localiza e carrega automaticamente o ambiente de desenvolvedor do MSVC, para que você não precise do prompt de comando embutido x64.

O exemplo desta documentação compila módulos de extensão C usando setuptools com o MSVC. Geralmente, você define QISKIT_PYTHON_EXTENSION, inclui qiskit.h e chama qk_import() na sua função de inicialização. Apenas os cabeçalhos de qiskit.capi.get_include() são necessários no momento da compilação — nenhuma biblioteca é vinculada. Consulte Estender o Qiskit em Python com C para mais detalhes.

Carregue o ambiente MSVC

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)

Verifique a configuração

Verifique se a configuração funcionou:

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.")

Etapa 4 - Teste de fumaça: compile uma extensão C

Execute o seguinte código. Ele grava arquivos-fonte em _smoke_pkg/, compila uma extensão C usando a API C do Qiskit e importa o resultado. Se ele imprimir "SMOKE TEST PASSED", sua toolchain está pronta.

O pacote segue o processo Estender o Qiskit em Python com C e usa funções da referência da API C do Qiskit.

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.")

Etapa 5 — Configurar o VS Code (opcional)

Para facilitar o uso, você pode seguir este processo para configurar o IntelliSense para arquivos C e selecionar automaticamente o interpretador Python.

Criar o diretório .vscode

No terminal do VS Code, execute o seguinte código:

mkdir $WORKSPACE\.vscode -Force

Criar o arquivo de configurações

Crie .vscode/settings.json no seu workspace executando este código:

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

Criar o arquivo de propriedades

O código a seguir imprime o JSON que você precisa colar em .vscode/c_cpp_properties.json:

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('}')

Criar o arquivo de extensões do VS Code

No VS Code, crie .vscode/extensions.json com este conteúdo:

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

Compilar a biblioteca independente

Esta seção compila a biblioteca C standalone, que só é necessária se você quiser compilar e vincular programas C puros, conforme descrito na seção UNIX-like. Além dos pré-requisitos da Etapa 1, isso requer as seguintes ferramentas:

• Um compilador Rust: veja por exemplo o guia sobre como instalar o Qiskit a partir do código-fonte

• cbindgen: uma ferramenta para criar o cabeçalho C, que você pode instalar com cargo install cbindgen. Executar a ferramenta a partir da linha de comando deve estar habilitado, o que pode exigir atualizar sua variável PATH para incluir o caminho do cargo.

• Uma instalação do Python com acesso tanto a python3.lib quanto a python3.dll

• Um clone do repositório do Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Compilar a biblioteca standalone

Primeiro, compile a biblioteca dinâmica qiskit_cext, executando o seguinte no terminal do VS Code (PowerShell) na raiz do Qiskit:

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

Isso irá gerar a biblioteca dinâmica .dll e o arquivo .dll.lib associado em target/release. Em seguida, gere o cabeçalho com

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

Isso escreve o cabeçalho compatível com MSVC em dist\c\include.

Agora você pode usar cl para compilar o programa C. Para garantir que o compilador encontre a biblioteca do Qiskit, inclua target\release na variável PATH.

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

Antes de executar, inclua o caminho para o seu python3.dll.

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

deve então imprimir

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] }

Solução de problemas

winget não é reconhecido

Atualize o App Installer na Microsoft Store, ou use os links de download manual relevantes

cl não é reconhecido

Execute novamente a célula de carregamento do MSVC (Etapa 3), ou use o x64 Native Tools Command Prompt

python abre a Microsoft Store

Vá em Configurações → Aplicativos → Configurações avançadas de aplicativos → Aliases de execução de aplicativos e desative python.exe

.ps1 cannot be loaded / scripts desabilitados

Execute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned e tente novamente

cannot open file 'qiskit.h'

Execute python -c "import qiskit.capi; print(qiskit.capi.get_include())" e confirme se o caminho existe

qiskit.capi não encontrado

Execute pip install "qiskit[visualization]~=2.4.2"

A compilação do qiskit-aer falha

Execute pip install qiskit-aer --only-binary=:all:. Se isso também falhar, use o Python 3.12 ou pule o aer, que é opcional

A compilação é executada, mas a importação falha com um erro de versão

A extensão C do Qiskit compilada e a versão do Qiskit instalada precisam ter a mesma versão. Reinstale o Qiskit com pip install "qiskit~=2.4.2"

Recompilei o C, mas o circuito não mudou

Uma extensão C não pode ser reimportada em tempo real. Reinicie o kernel, execute novamente os comandos do MSVC (Etapa 3) e depois recompile

O script do PowerShell foi bloqueado

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Erros de comprimento de caminho

Use um caminho raiz curto em C:\ (por exemplo, C:\workspace, ou o caminho que você definiu na etapa de configuração), ou habilite Caminhos Longos: Configurações → Sistema → Para desenvolvedores → Caminhos Longos

O Conda está ativo (o prompt mostra (base)) ou as compilações se comportam de forma estranha após usar o Anaconda

Execute conda deactivate até que CONDA_DEFAULT_ENV e CONDA_PREFIX desapareçam do ambiente. Verifique com $env:CONDA_PREFIX. Se persistirem, abra um novo PowerShell (não um prompt do Anaconda) e tente novamente a partir da Etapa 2.

O ambiente virtual foi criado a partir de um Python gerenciado pelo conda (verifique a linha home = em .venv\pyvenv.cfg)

O ambiente virtual herdou o runtime C do conda e não pode ser corrigido no local. Exclua-o, baixe o Python 3.12 no site do Python e recompile. Execute Remove-Item -Recurse -Force .venv, depois execute novamente o snippet de detecção do Python na Etapa 1 para definir $PYTHON_EXE, e então recrie o ambiente virtual (Etapa 2).

DLL load failed ao importar

É provável que o conda esteja vazando para dentro do ambiente virtual. Verifique os dois problemas imediatamente acima. Verifique também se o Python é de 64 bits: python -c "import platform; print(platform.architecture())"

A compilação falha com caminhos ilegíveis ou C1083

Seu nome de usuário ou caminho do workspace contém caracteres não ASCII. Mova o workspace para um caminho curto somente ASCII (por exemplo, C:\workspace)

A compilação ou a importação falha aleatoriamente, mas funciona ao tentar de novo

A pasta do workspace está sincronizada pelo OneDrive. Mova-a para um caminho local como C:\workspace

Compilação interrompida no meio (por exemplo, houve uma queda de energia)

Exclua a pasta _smoke_pkg no seu workspace, execute novamente a célula de carregamento do MSVC e, em seguida, execute novamente a célula do smoke test

pip install falha com erro de certificado SSL

Sua rede usa um proxy que intercepta o HTTPS. Tente executar pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit ou peça ao administrador da rede o certificado CA do proxy

O Windows Defender coloca o arquivo .pyd em quarentena

Adicione as pastas .venv e _smoke_pkg do seu workspace às exclusões do Defender indo em Segurança do Windows → Proteção contra vírus e ameaças → Gerenciar configurações → Exclusões

Não é possível instalar o VS Build Tools (sem direitos de administrador)

É necessário acesso de administrador. Peça acesso ao seu departamento de TI

WinError 32 / arquivo em uso durante a recompilação

O .pyd está bloqueado pelo kernel em execução. Reinicie o kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), execute novamente a Etapa 3 e depois recompile

Os comandos não fazem nada silenciosamente (sem erro, sem saída)

Você pode estar no cmd.exe em vez do PowerShell. Verifique seu prompt: o PowerShell mostra PS C:\>, o cmd mostra C:\>. Abra o PowerShell pelo Menu Iniciar ou Win+X

A instalação do MSVC parece travada

As flags --passive --wait bloqueiam o PowerShell enquanto o instalador é executado em segundo plano. Verifique sua barra de tarefas em busca de uma janela "Visual Studio Installer". Pode levar de 10 a 30 minutos para instalar

Próximas etapas

Recommendations

• Saiba como estender o Python com a API C do Qiskit.
• Instale o Qiskit.
• Explore a referência da API C do Qiskit.

Footnotes

1. Se você não instalou o Make, verifique o Makefile na raiz do Qiskit para os comandos necessários — ou simplesmente instale o Make; ainda dá tempo. ↩