Qiskit IonQ Provider

1.0.2 verified Sat May 09 auth: no python

Qiskit provider for IonQ backends, enabling users to run quantum circuits on IonQ's trapped-ion quantum computers via the IonQ API. Current version: 1.0.2, requires Python >=3.10 and Qiskit >=2.0. Releases are on-demand.

pip install qiskit-ionq

Common errors

error ImportError: cannot import name 'IonQProvider' from 'qiskit_ionq' ↓

cause Using an outdated version (<1.0.0) where the class was named differently or not exported.

fix

Upgrade to the latest version: pip install --upgrade qiskit-ionq

error TypeError: backend.run() got an unexpected keyword argument 'circuits' ↓

cause Passing circuits as keyword argument 'circuits' instead of positional argument.

fix

Use backend.run(circuit, shots=1024) instead of backend.run(circuits=circuit, ...).

error qiskit_ionq.exceptions.IonQAuthenticationError: 401 Client Error: Unauthorized ↓

cause Missing or invalid API token.

fix

Set the IONQ_API_TOKEN environment variable or pass a valid token to IonQProvider.

Warnings

breaking Version 1.0.0+ requires Qiskit >=2.0. Older versions of qiskit-ionq (0.x) are incompatible with Qiskit >=2.0. Upgrade both together. ↓

fix Upgrade Qiskit to 2.x and qiskit-ionq to 1.x: pip install 'qiskit>=2.0' 'qiskit-ionq>=1.0.0'

breaking The `run` method now expects circuits to be in a Qiskit `QuantumCircuit` object, not a list of `Instruction` or `Operation` objects. ↓

fix Ensure you pass circuits as `QuantumCircuit` instances: `backend.run(qc)`

gotcha IonQProvider accepts a token via constructor parameter or environment variable IONQ_API_TOKEN. Not providing either will raise an authentication error. ↓

fix Set the IONQ_API_TOKEN environment variable or pass token='your_token' to IonQProvider.

Install

pip install 'qiskit-ionq[visualization]'

Imports

IonQProvider
wrong
```
from qiskit_ionq.providers import IonQProvider
```
correct
```
from qiskit_ionq import IonQProvider
```
IonQProvider is a top-level export in qiskit_ionq, not in a submodule.
IonQBackend
wrong
```
from qiskit.providers.ionq import IonQBackend
```
correct
```
from qiskit_ionq import IonQBackend
```
IonQBackend is exported from qiskit_ionq directly; it is not part of Qiskit's core providers.

Quickstart

Runs a Bell state circuit on the IonQ simulator backend. Requires IONQ_API_TOKEN environment variable.

from qiskit_ionq import IonQProvider
from qiskit import QuantumCircuit

# Initialize provider with your API token from environment variable
provider = IonQProvider(token=os.environ.get('IONQ_API_TOKEN', 'your_token_here'))

# Get backend
backend = provider.get_backend('ionq_simulator')

# Create a simple Bell state circuit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Run the circuit
job = backend.run(qc, shots=1024)
print(job.result().get_counts())