PyQuil

4.17.0 verified Fri May 01 auth: no python

PyQuil is a Python library for creating and running Quantum Instruction Language (Quil) programs on Rigetti quantum processors and simulators. The current version is 4.17.0, supporting Python 3.9-3.12. It sees regular releases alongside Rigetti's Forest SDK.

pip install pyquil

Common errors

error ModuleNotFoundError: No module named 'pyquil.api' ↓

cause Incorrect import path: users try `from pyquil.api import ...` but the module is not installed or deprecated in older versions.

fix

Use from pyquil import get_qc for the quantum computer object; API classes are under pyquil.api but may require separate import.

error AttributeError: 'Program' object has no attribute 'run' ↓

cause In PyQuil 4.x, programs are not directly runnable; they must be compiled first.

fix

Replace program.run(qc) with qc.compile(program) then qc.run(executable).

error TypeError: 'QuantumComputer.run()' got an unexpected keyword argument 'shots' ↓

cause In PyQuil 4.x, the `run()` method no longer accepts `shots`; the number of shots is set in the program via `measurements` or in the `compile` step.

fix

Set shots via program.wrap_in_numshots_loop(N) before compiling.

Warnings

breaking PyQuil 4.x introduced breaking changes from 3.x: import paths changed (e.g., `from pyquil.api` instead of `from pyquil.quilbase`), and the `QuantumComputer.run()` now expects compiled executables, not programs. ↓

fix Update import statements and use `qc.compile(program)` before running.

deprecated The `from pyquil.quil` module and `from pyquil.parser` are deprecated in 4.x. Use `from pyquil import Program` and `from pyquil.gates` for gate definitions. ↓

fix Switch to the new import paths; see migration guide.

gotcha When using `get_qc('2q-qvm')`, the QVM (quantum virtual machine) is a simulator that requires the QVM server to be running locally or via Forest SDK. Without it, calls to `run` will hang or fail with connection errors. ↓

fix Ensure the QVM server is running: `qvm -S` in a separate terminal, or use a remote QPU endpoint.

Imports

Program
```
from pyquil import Program
```
get_qc
wrong
```
from pyquil.api import get_qc
```
correct
```
from pyquil import get_qc
```
In v4.x, get_qc is a top-level import; the submodule path changed.

AbstractCompiler

wrong

from pyquil.compiler import AbstractCompiler

correct

from pyquil.api import AbstractCompiler

Common mistake due to old docs; correct module is pyquil.api.

Quickstart

Minimal example creating a Bell state circuit and running on the QVM simulator.

from pyquil import Program, get_qc
from pyquil.gates import H, CNOT, MEASURE

# Create a Bell state program
p = Program()
p += H(0)
p += CNOT(0, 1)
ro = p.declare('ro', 'BIT', 2)
p += MEASURE(0, ro[0])
p += MEASURE(1, ro[1])

# Get a quantum computer (simulator)
qc = get_qc('2q-qvm')

# Run the program
executable = qc.compile(p)
result = qc.run(executable)
print(result.readout.get('ro'))