Saltar al contenido principal
Este proyecto está en fase beta. ¿Encontraste un error? Abre un issue en GitHub. ¿Tienes una pregunta o una idea? Pregunta en Discussions — ¡nos encantaría tu opinión!
¿Cómo es la calidad de la traducción en esta página?

Instalar la API C de Qiskit

Esta guía describe cómo instalar y usar la API C de Qiskit. Después de completar la instalación, lee Extender Python con la API C de Qiskit.

El siguiente ejemplo construye un observable con 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;
}

Sistemas tipo UNIX​

Esta sección proporciona instrucciones de compilación para sistemas tipo UNIX.

Requisitos​

La compilación requiere las siguientes herramientas:

  • Un compilador de Rust: consulta, por ejemplo, la guía para instalar Qiskit desde el código fuente
  • Un compilador de C: por ejemplo, GCC en Linux y Clang en MacOS. La API C de Qiskit es compatible con compiladores que cumplan el estándar C11.
  • cbindgen: una herramienta para crear el encabezado C, que puedes instalar con cargo install cbindgen La herramienta debe poder ejecutarse desde la línea de comandos, para lo que quizá tengas que exportar tu variable PATH para incluir /path/to/.cargo/bin.
  • Biblioteca de Python instalada (Python 3.9+): La biblioteca de Python es necesaria durante el enlazado dinámico. Ten en cuenta que Python no se usa en tiempo de ejecución y el intérprete nunca se inicializa; solo algunos símbolos de libpython necesitan estar definidos. Consulta este issue para más detalles.
  • (GNU) Make: esto es opcional pero se recomienda para usar procesos de instalación automatizados.

Este código verifica que todo esté instalado correctamente:

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

Compilación​

Para compilar el encabezado C y la biblioteca, puedes ejecutar el siguiente comando Make1 en la raíz de Qiskit,

make c

lo que proporcionará la biblioteca compartida compilada en dist/c/lib y el encabezado qiskit.h con todas las declaraciones de funciones en dist/c/include. Ten en cuenta que el nombre exacto de la biblioteca depende de la plataforma; por ejemplo, libqiskit.so en UNIX y libqiskit.dylib en MacOS. (Ten en cuenta que este paso actualmente emite muchas advertencias, lo cual es esperado y no es motivo de alarma. Las versiones futuras eliminarán estas advertencias.)

Luego puedes compilar un programa en C usando el encabezado y la biblioteca C de Qiskit:

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

Para asegurarte de que la biblioteca de Qiskit se encuentre durante el enlazado, establece la ruta de la biblioteca en tiempo de ejecución para incluir /path/to/dist/c/lib. Si la biblioteca de Python no está disponible por defecto durante el enlazado dinámico, también es necesario agregarla. Estos comandos dependen de la plataforma. En 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

En MacOS:

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

Alternativamente, puedes establecer la ruta de la biblioteca en tiempo de ejecución durante la compilación agregando

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

a los flags del compilador. Además, la biblioteca de Python debe estar disponible durante el enlazado dinámico. En entornos Linux esto suele ser el comportamiento por defecto.

Ahora puedes ejecutar el binario:

./example.o

que, si usas el fragmento de ejemplo mostrado anteriormente, debería 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 sección proporciona instrucciones de compilación para sistemas Windows.

Hay dos formas independientes de usar la API C en Windows:

  • Construir módulos de extensión de Python que usen la API C de Qiskit. Sigue los pasos 1-5. Esta ruta usa los encabezados C incluidos con el paquete Python qiskit y no requiere Rust ni cbindgen.

  • Construir la biblioteca C independiente para enlazarla desde un programa C puro, como se hace en la sección tipo UNIX. Completa el paso 1, luego pasa a Construir la biblioteca independiente, que enumera sus requisitos adicionales.

Requisitos​

  • Se requieren permisos de administrador para algunos pasos.

  • 5-8 GB de espacio libre en disco.

  • Un compilador de C: Microsoft Visual C++ (MSVC), instalado en el paso 1.

  • Una instalación de Python de 64 bits (3.10 o posterior), instalada en el paso 1.

Antes de empezar​

Crea tu espacio de trabajo. Esto debe ser una ruta corta en una unidad local. No uses carpetas sincronizadas con OneDrive (como Documents o Desktop), unidades de red, ni rutas con espacios o caracteres no ASCII. Si tu nombre de usuario contiene caracteres no ingleses, no lo pongas dentro de tu carpeta de usuario.

Ejemplos de buenas rutas de espacio de trabajo: C:\workspace, D:\workspace, C:\Users\john\workspace

Paso 1. Instala los requisitos previos​

MSVC Build Tools (compilador de C) — instala esto primero

Esta es una descarga grande (2-5 GB, 10-30 min). Instálala primero para saber de inmediato si tu ordenador es compatible.

nota

Requires administrator rights.

Opción A — winget Abre una terminal de PowerShell y ejecuta lo siguiente:

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

La terminal parece congelada mientras se ejecuta el instalador. Esto es normal y tardará entre 10 y 30 minutos. Comprueba tu barra de tareas para ver una ventana de "Visual Studio Installer".

Si winget no se reconoce, actualiza App Installer desde la Microsoft Store, o usa la Opción B.

Opción B — descarga manual Abre el sitio web de Visual Studio Build Tools para C++ y haz clic en Download Build Tools. Ejecuta el archivo ejecutable para iniciar la instalación.

Cuando se abra la ventana de Installing Visual Studio, en la pestaña Workloads, elige "Desktop development with C++". Consulta la página Install C and C++ support in Visual Studio para más detalles.

VS Code

Descarga VS Code desde el sitio de Visual Studio Code, o ejecuta winget install Microsoft.VisualStudio.Code. Ejecuta el archivo ejecutable descargado para instalar VS Code.

Una vez instalado, continúa con estos pasos:

  1. Abre VS Code
  2. Haz clic en File → Open Folder, luego selecciona tu espacio de trabajo (por ejemplo, C:\workspace).
  3. Haz clic en Terminal → New terminal para abrir una terminal de PowerShell.
  4. Haz clic en el icono de Extensions a la izquierda o pulsa Ctrl+Shift+X. En la ventana de Extensions, busca e instala ms-python.python, ms-toolsai.jupyter, y ms-vscode.cpptools.

Ejecuta el resto de los comandos de esta guía en la terminal de VS Code, salvo que se indique lo contrario. La terminal de VS Code usa PowerShell por defecto, evitando confusiones con la ventana de comandos integrada de Windows.

Establece la variable de espacio de trabajo. Por ejemplo, si tu espacio de trabajo se llama workspace, ejecuta lo siguiente:

$WORKSPACE = "C:\workspace"   # change to your workspace path
mkdir $WORKSPACE -Force
cd $WORKSPACE
Python 3.12 (versión recomendada)

Se recomienda Python 3.12 porque tiene la mejor disponibilidad de wheels para qiskit-aer y otras dependencias. 3.10 y 3.11 también funcionan, pero 3.13 o posterior podrían carecer de wheels precompilados para algunos paquetes.

Abre la terminal de VS Code y ejecuta el siguiente código para detectar una versión adecuada de 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'" }

Si la descarga no funcionó, o prefieres una descarga manual, comenta las líneas de código que instalan Python 3.12, luego descarga Python 3.12 desde el sitio web de Python. Ejecuta el archivo ejecutable para instalar Python. Selecciona "Add Python to PATH" durante la instalación, luego vuelve a ejecutar el fragmento anterior para asegurarte de que se encuentra.

Notas

  • NO uses el Python de la Microsoft Store porque carece de encabezados C. Si python abre la Microsoft Store, desactiva el alias yendo a Configuración de Windows → Aplicaciones → Configuración avanzada de aplicaciones → Alias de ejecución de aplicaciones.

  • Usuarios de Anaconda: ejecuta conda deactivate hasta que desaparezca el prefijo (base). Si no desaparece, abre una nueva terminal en VS Code.

Git (opcional)

Solo es necesario si clonas repositorios de laboratorio. Ejecuta winget install Git.Git.

Paso 2 - Configura el entorno virtual de Python con Qiskit​

Reinicia la terminal de VS Code

Abre la terminal de VS Code y reinícala:

$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'"
}
Crea y activa un entorno virtual

Permite la ejecución de scripts (una vez por usuario), luego crea el entorno virtual:

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

Si la activación muestra un error rojo sobre "scripts disabled", la línea Set-ExecutionPolicy no se ejecutó. Ejecútala manualmente y vuelve a intentarlo.

Tu prompt ahora debería mostrar (workspace).

Verify:

Get-Command python | Select-Object -First 1 -ExpandProperty Source
# → workspace\.venv\Scripts\python.exe
Instala paquetes
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 desde el código fuente. Si qiskit-aer sigue fallando, intenta pip install qiskit-aer --only-binary=:all: u omítelo. qiskit-aer es opcional y solo se necesita para la simulación local.

nota

NO ejecutes pip install --upgrade qiskit después de la configuración. Actualizar a una nueva versión menor rompe las extensiones de C compiladas contra la versión anterior.

Paso 3 - Carga el entorno de MSVC​

Ejecuta el siguiente código en cada nueva sesión de Python (por ejemplo, cada vez que reinicies un kernel de Jupyter). Localiza y carga automáticamente el entorno de desarrollo de MSVC para que no necesites el símbolo del sistema integrado x64.

El ejemplo de esta documentación crea módulos de extensión en C usando setuptools con MSVC. En general, defines QISKIT_PYTHON_EXTENSION, incluyes qiskit.h y llamas a qk_import() en tu función de inicialización. Solo se necesitan los encabezados de qiskit.capi.get_include() en el momento de la compilación; no se enlaza ninguna biblioteca. Consulta Extender Qiskit en Python con C para más detalles.

Cargar el entorno de 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)
Verificar la configuración

Verifica que la configuración funcionó:

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

Paso 4 - Prueba de humo: Compilar una extensión en C​

Ejecuta el siguiente código. Escribe archivos fuente en _smoke_pkg/, compila una extensión en C contra la API C de Qiskit e importa el resultado. Si imprime "SMOKE TEST PASSED", tu cadena de herramientas está lista.

El paquete sigue el proceso de Extender Qiskit en Python con C y usa funciones de la referencia de la API C de Qiskit.

Código de la prueba de humo
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.")

Paso 5 — Configurar VS Code (opcional)​

Para facilitar el uso, puedes seguir este proceso para configurar IntelliSense para archivos C y seleccionar automáticamente el intérprete de Python.

Crear el directorio .vscode

En la terminal de VS Code, ejecuta el siguiente código:

mkdir $WORKSPACE\.vscode -Force
Crear el archivo de configuración

Crea .vscode/settings.json en tu espacio de trabajo ejecutando este código:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "python.terminal.activateEnvironment": true,
    "jupyter.notebookFileRoot": "${workspaceFolder}"
}
Crear el archivo de propiedades

El siguiente código imprime el JSON que necesitas pegar en .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('}')
Crear el archivo de extensiones de VS Code

En VS Code, crea .vscode/extensions.json con este contenido:

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

Compilar la biblioteca independiente​

Esta sección compila la biblioteca C independiente, que solo se necesita si quieres compilar y enlazar programas en C puro, como se describe en la sección tipo UNIX. Además de los requisitos previos del Paso 1, esto requiere las siguientes herramientas:

  • Un compilador de Rust: consulta, por ejemplo, la guía sobre instalar Qiskit desde el código fuente

  • cbindgen: una herramienta para crear el encabezado C, que puedes instalar con cargo install cbindgen. Ejecutar la herramienta desde la línea de comandos debería estar habilitado, lo que podría requerir actualizar tu variable PATH para incluir la ruta de cargo.

  • Una instalación de Python con acceso tanto a python3.lib como a python3.dll

  • Un clon del repositorio de Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Compilar la biblioteca independiente

Primero, compila la biblioteca dinámica qiskit_cext, ejecutando lo siguiente en la terminal de VS Code (PowerShell) en la raíz de Qiskit:

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

Esto generará la biblioteca dinámica .dll y el archivo .dll.lib asociado en target/release. A continuación, genera el encabezado con:

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

Esto escribe el encabezado compatible con MSVC en dist\c\include.

Ahora puedes usar cl para compilar el programa en C. Para asegurarte de que el compilador encuentre la biblioteca de Qiskit, incluye target\release en la variable PATH.

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

Antes de ejecutarlo, incluye la ruta a tu python3.dll.

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

debería entonces 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] }

Solución de problemas​

winget no se reconoce

Actualiza el App Installer desde la Microsoft Store, o usa los enlaces de descarga manual correspondientes

cl no se reconoce

Vuelve a ejecutar la celda de carga de MSVC (Paso 3), o usa el x64 Native Tools Command Prompt

python abre Microsoft Store

Ve a Configuración → Aplicaciones → Configuración avanzada de aplicaciones → Alias de ejecución de aplicaciones y desactiva python.exe

.ps1 cannot be loaded / scripts deshabilitados

Ejecuta Set-ExecutionPolicy -Scope CurrentUser RemoteSigned y vuelve a intentarlo

cannot open file 'qiskit.h'

Ejecuta python -c "import qiskit.capi; print(qiskit.capi.get_include())" y confirma que la ruta existe

qiskit.capi no se encuentra

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

Falla la compilación de qiskit-aer

Ejecuta pip install qiskit-aer --only-binary=:all:. Si eso también falla, usa Python 3.12 u omite aer, que es opcional

La compilación se ejecuta pero la importación falla con un error de versión

La extensión C de Qiskit compilada y la versión de Qiskit instalada deben tener la misma versión. Reinstala Qiskit con pip install "qiskit~=2.4.2"

Recompilé el código C pero el circuito no cambió

Una extensión C no se puede volver a importar en caliente. Reinicia el kernel, vuelve a ejecutar los comandos de MSVC (Paso 3) y luego recompila

El script de PowerShell fue bloqueado

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Errores de longitud de ruta

Usa una ruta raíz corta en C:\ (por ejemplo, C:\workspace, o la ruta que configuraste en el paso de instalación), o habilita Long Paths: Configuración → Sistema → Para desarrolladores → Long Paths

Conda está activo (el prompt muestra (base)) o las compilaciones se comportan de forma extraña después de usar Anaconda

Ejecuta conda deactivate hasta que CONDA_DEFAULT_ENV y CONDA_PREFIX desaparezcan del entorno. Comprueba con $env:CONDA_PREFIX. Si persisten, abre una PowerShell nueva (no un Anaconda prompt) y vuelve a intentarlo desde el Paso 2.

El entorno virtual se creó a partir de un Python administrado por conda (revisa la línea home = en .venv\pyvenv.cfg)

El entorno virtual heredó el runtime C de conda y no se puede arreglar en el lugar. Elimínalo, descarga Python 3.12 desde el sitio web de Python y vuelve a compilar. Ejecuta Remove-Item -Recurse -Force .venv, luego vuelve a ejecutar el fragmento de detección de Python del Paso 1 para configurar $PYTHON_EXE, y luego vuelve a crear el entorno virtual (Paso 2).

DLL load failed al importar

Es probable que conda esté filtrándose en el entorno virtual. Revisa ambos problemas inmediatamente anteriores a este. También verifica que Python sea de 64 bits: python -c "import platform; print(platform.architecture())"

La compilación falla con rutas ilegibles o C1083

Tu nombre de usuario o la ruta del espacio de trabajo contiene caracteres no ASCII. Mueve el espacio de trabajo a una ruta corta que use solo ASCII (por ejemplo, C:\workspace)

La compilación o la importación falla de forma aleatoria, pero funciona al reintentar

La carpeta del espacio de trabajo se sincroniza con OneDrive. Muévela a una ruta local como C:\workspace

Compilación interrumpida a medias (por ejemplo, por un corte de energía)

Elimina la carpeta _smoke_pkg en tu espacio de trabajo, vuelve a ejecutar la celda de carga de MSVC y luego vuelve a ejecutar la celda de la prueba de humo

pip install falla con un error de certificado SSL

Tu red usa un proxy que intercepta HTTPS. Intenta ejecutar pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit o pide a tu administrador de red el certificado CA del proxy

Windows Defender pone en cuarentena el archivo .pyd

Agrega las carpetas .venv y _smoke_pkg de tu espacio de trabajo a las exclusiones de Defender yendo a Seguridad de Windows → Protección contra virus y amenazas → Administrar configuración → Exclusiones

VS Build Tools no se puede instalar (sin derechos de administrador)

Se requiere acceso de administrador. Pide acceso a tu departamento de TI

WinError 32 / archivo en uso durante la recompilación

El .pyd está bloqueado por el kernel en ejecución. Reinicia el kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), vuelve a ejecutar el Paso 3 y luego recompila

Los comandos no hacen nada en silencio (sin error ni salida)

Es posible que estés en cmd.exe en lugar de PowerShell. Comprueba tu prompt: PowerShell muestra PS C:\>, cmd muestra C:\>. Abre PowerShell desde el menú Inicio o Win+X

La instalación de MSVC parece bloqueada

Los indicadores --passive --wait bloquean PowerShell mientras el instalador se ejecuta en segundo plano. Comprueba tu barra de tareas para ver una ventana de "Visual Studio Installer". Puede tardar de 10 a 30 minutos en instalarse

Próximos pasos​

Recomendaciones

Footnotes​

  1. Si no instalaste Make, revisa el Makefile en la raíz de Qiskit para ver los comandos necesarios — o simplemente instala Make; todavía estás a tiempo. ↩

Fuente: Documentación de IBM Quantum — actualizado el 17 jul 2026
Versión en inglés en doQumentation — actualizado el 17 jul 2026
¿Problema con el sitio o la traducción?¿Problema de contenido? Editar en IBM Quantum docs