localqpu

A local emulator of the IBM Quantum Platform API, built for testing. Like a payment provider's "test mode", it lets you test code that calls a quantum cloud without queues, without cost, and with any failure you want to simulate.

localqpu does not verify that quantum results are correct. It verifies the code around the quantum API call: submission, waiting, retries, result parsing, and error handling.

Install and run

pip install localqpu      # https://pypi.org/project/localqpu/
localqpu start            # http://127.0.0.1:8787

Docker

Multi-arch images (amd64, arm64) are published to GHCR for every release from v0.2.0 on:

docker run -p 127.0.0.1:8787:8787 ghcr.io/ictechgy/localqpu:latest

The image runs as an unprivileged user and has a HEALTHCHECK on /_localqpu/health, so it works as a CI service container — handy when the code under test is not Python:

# GitHub Actions
services:
  localqpu:
    image: ghcr.io/ictechgy/localqpu:latest
    ports: ["8787:8787"]

Connect existing Qiskit code

import localqpu

service = localqpu.connect(port=8787)  # use this instead of QiskitRuntimeService(...)
backend = service.least_busy()

⚠️ Always use localqpu.connect(). In qiskit-ibm-runtime the runtime authentication endpoint is hard-coded to iam.cloud.ibm.com and can only be changed through the IAM_URL environment variable. If you configure the client by hand and miss it, the client sends your key to the real IBM Cloud. connect() sets IAM_URL and routes both HTTP and HTTPS through localqpu, so any leaking HTTPS request is blocked. Blocked attempts are counted in blocked_connect_requests on GET /_localqpu/health.

Note that connect() changes process-wide environment variables: it sets IAM_URL and appends localqpu.test to NO_PROXY/no_proxy (so that HTTP_PROXY settings cannot redirect localqpu traffic to a corporate proxy). Run tests that talk to the real IBM Cloud in a separate process.

AWS Braket (experimental)

Install the extra (Python 3.11+, because the Braket packages require it) and point the Amazon Braket SDK at localqpu:

pip install 'localqpu[braket]'

import localqpu
from braket.aws import AwsDevice
from braket.circuits import Circuit

session = localqpu.connect_braket(port=8787)
device = AwsDevice("arn:aws:braket:::device/quantum-simulator/amazon/sv1", aws_session=session)
counts = device.run(Circuit().h(0).cnot(0, 1), shots=100).result().measurement_counts

• Emulates the SV1 simulator only, for gate-model OpenQASM tasks: create/get/cancel quantum tasks, get/search devices, and the S3 results.json download. Tasks share the job manager with IBM jobs, so failure scenarios (next_jobs, failures, queue) apply to them too.
• ⚠️ connect_braket() changes process-wide environment variables: it points AWS_ENDPOINT_URL (and the S3/Braket/STS-specific variants) at localqpu. The Braket SDK copies sessions internally and the copies lose explicitly passed clients — without this, result downloads went to the real AWS S3. With it, any AWS call the SDK makes lands on localqpu (unknown ones fail with 501) instead of leaking.
• Qubits are limited by --max-sim-qubits (all declared qubits count, since entanglement is not analysed for Braket programs). There is no stub mode and no seed control for Braket tasks.

Use with pytest

The fixtures are registered automatically once the package is installed.

def test_retry_on_failure(localqpu_service, localqpu_control):
    localqpu_control.set_scenario({"next_jobs": [{"outcome": "failed", "reason": "calibrating"}]})
    ...

Failure scenarios

Use localqpu start --scenario scenario.json or localqpu_control.set_scenario({...}).

{
  "seed": 42,
  "queue": { "delay_seconds": 0, "polls_before_running": 1 },
  "failures": { "rate": 0.0, "reason": "Simulated failure", "reason_code": 9999 },
  "next_jobs": [
    { "outcome": "failed", "reason": "QPU calibration in progress", "reason_code": 1517 },
    { "outcome": "cancelled" }
  ],
  "backends": { "ibm_brisbane": { "status": "offline", "queue_length": 120 } },
  "usage": { "limit_seconds": 600, "consumed_seconds": 600 },
  "auth": { "reject_tokens": false },
  "noise": false
}

QiskitRuntimeService caches the backend list after the first least_busy()/backends() call, exactly as it does against IBM. After changing backend status in a scenario, create a new service (the localqpu_service fixture gives you a fresh one per test).

Control API

Supported primitives

All of them also work inside Session(...) and Batch(...).

Simulation size

Circuits arrive laid out on the full chip (e.g. 127 qubits), but what makes simulation expensive is entanglement, not width. localqpu therefore limits the number of entangled qubits — qubits touched by multi-qubit gates — with --max-sim-qubits (default 24), and simulates exactly with Aer's matrix-product-state method, which is cheap for qubits that only get single-qubit gates or measurements. Above the limit you get a stub instead of an error: sampler and estimator return shape-correct random values (metadata["localqpu_stub"]), and executor runs an approximate simulation with a capped MPS bond dimension, so the result structure is exact but the values are not meaningful. Stub jobs are flagged with is_stub: true in GET /_localqpu/jobs and logged by the server.

Limitations

• IBM Quantum Platform, plus AWS Braket SV1 as an experimental extra. Qiskit Functions are not supported yet.
• Session and Batch are supported (create, status, close(), cancel(), from_id), but session timeouts (max_time, interactive timeout) are not emulated.
• Noiseless by default; set "noise": true in the scenario to add the chip's noise model.
• Jobs are kept in memory only and are lost when the server restarts.
• A running simulation cannot be interrupted. POST /_localqpu/reset (used by the pytest fixtures between tests) discards its result and starts a fresh worker pool, so later jobs are not blocked, but the old computation keeps using CPU until it finishes.
• Failure reasons use localqpu codes: 9000 for localqpu-side failures (invalid input, simulation limits) and 9001 for user cancellation.