PyQuil programming, simulation, and QPU execution

PyQuil's role in a Forest SDK workflow

PyQuil addresses the programming layer between Python and Quil, the quantum instruction language developed at Rigetti Computing. Its intended users are Python developers writing quantum programs for local simulation, compilation, or execution on Rigetti quantum processing units. The library is not a complete simulator or compiler by itself. It represents programs and communicates with separate parts of the Forest SDK, including quilc for compilation and the Quantum Virtual Machine for simulation.

This separation makes the data flow explicit. A Python application constructs a `Program` from Quil gates, declarations, measurements, and other instructions. PyQuil can then submit that representation to a QVM or QPU service, while quilc transforms selected programs for supported hardware. For execution through Quantum Cloud Services, the remote service and an account introduce additional operational dependencies that do not apply to ordinary Python-only workflows.

The current package metadata targets Python `>=3.11, <3.13`. That restriction matters when selecting an environment. The repository version is `4.23.0rc1`, which is a release candidate rather than the stable `4.22.0` release listed with a published date. An installation directly from the repository should therefore be treated separately from installing the package available from PyPI.

Constructing Bell-state instructions with Program and gates

The README's first program builds a two-qubit Bell-state circuit through small, readable operations. `H` applies a Hadamard gate to qubit 0, and `CNOT(0, 1)` entangles qubit 0 with qubit 1. The program then declares a two-bit classical register named `ro`, measures both qubits into separate register entries, and wraps the circuit in a 10-shot loop.

This API exposes the quantum control flow instead of hiding it behind a separate circuit notation. Instructions are added with `Program` operators, register declarations use `declare`, and gate constructors come from `pyquil.gates`. The return value from `get_register_map()` exposes the measured `ro` values. According to the README, repeated outputs such as `[0, 0]` and `[1, 1]` are consistent with an entangled two-qubit state.

The example also illustrates a practical boundary. The displayed shot results describe outcomes from the Bell circuit, but the README does not present them as a performance measurement or a claim about error rates. PyQuil is the program construction and service integration layer here. Measurement interpretation remains with the application or downstream analysis.

Installing PyQuil and obtaining the required services

PyPI installation is the shortest documented route. The README recommends using `pip` inside a virtual environment, although it does not include commands for creating that environment.

pip install pyquil

For development from a clone, the documented editable install is:

pip install -e .

Installing the Python package alone does not provide the full Forest SDK execution stack. The README states that full use also requires `quilc` and the QVM, pointing readers to their separate project documentation. The repository adds container definitions for both services through `docker-compose.yaml`, but it does not provide a complete one-command quickstart in the excerpted instructions. The Compose file starts `quilc` in server mode on port `5555` and the QVM on port `5000`.

That distinction prevents a common setup error: importing PyQuil can succeed while compilation or simulation still fails because its backing services are absent or not configured. Users should confirm both the Python dependency set and the separate Forest components before treating an installation as executable.

Running the first two-qubit simulation

The following is the complete first-use example documented in the README. It creates a QVM client for the `2q-qvm`, defines the Bell-state program, executes ten shots, requests the `ro` register map, and converts the register values to a Python list.

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

qvm = get_qc('2q-qvm')

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])
p.wrap_in_numshots_loop(10)

qvm.run(p).get_register_map()['ro'].tolist()

Before running it, the QVM must be available at the address expected by the Forest configuration. The repository Makefile writes a default local configuration through `make config`, using `http://localhost:5000` for `qvm_address` and `tcp://localhost:5555` for `quilc_address`. The README does not show the complete `make config` invocation in its quickstart, so the example should be read together with the service deployment and configuration steps.

The README shows ten outcome rows containing correlated pairs. Their order can vary between executions because quantum measurement is probabilistic. The relevant consistency stated by the README is that the records use `00` and `11` outcomes, which fits the intended entangled-state behavior.

Service boundaries for quilc, the QVM, and QPUs

The `get_qc` call in the quickstart selects an execution environment by name. This makes the README example simple, but it does not mean PyQuil contains a local quantum computer in the Python process. Execution is handed to the selected QVM, QPU, or connected service layer.

The repository's `docker-compose.yaml` provides concrete evidence of the local service split. `quilc` uses the `rigetti/quilc` image with the `-S` command and exposes port `5555`. `qvm` uses the `rigetti/qvm` image, also with `-S`, and exposes port `5000`. The Compose file is therefore an infrastructure definition rather than a PyQuil programming example.

QPU execution follows a different path. The README says that PyQuil can execute Quil programs on real quantum processors through Quantum Cloud Services and directs users to request QCS access. It does not document authentication commands, QPU names, reservation procedures, calibration handling, or execution limits. Those omissions make cloud adoption unsuitable for readers who need a fully specified runbook from this README alone. Hardware behavior, scheduling, and access conditions must be verified through QCS documentation.

Version, dependency, and maintenance constraints

The repository's last push was on 2026-10-15. It is not archived, and the listed release activity includes `v4.22.0` on 2026-10-08 and `v4.23.0rc1` on 2026-10-09. This indicates recent development activity, but the repository version remains an `rc1` build. Production users should distinguish that candidate version from the stable release rather than treating the branch state as a general availability guarantee.

The package metadata defines substantial dependencies, including `qcs-sdk-python`, `quil`, `numpy`, `scipy`, `networkx`, and `rigetti-quax`. Version bounds matter because PyQuil interfaces with both Python libraries and external services. The repository also includes `poetry.lock`, a `Dockerfile`, `Makefile` targets, tests, and documentation, indicating that the project is packaged as a maintained software component rather than a collection of isolated snippets.

PyQuil is licensed under Apache-2.0. The README identifies the license and directs readers to the repository `LICENSE`. Users still need to review that file for the applicable notices and obligations. The package metadata also declares `Apache Software License` under the OSI classifier. This is licensing information, not legal advice.

Where PyQuil is the wrong tool

PyQuil is the wrong choice when the only requirement is to simulate a small circuit locally without caring about Quil or the Forest service model. Its documented QVM path still requires a QVM installation or reachable service, and its full local environment also includes quilc. A project that needs only a general-purpose local simulator should not adopt PyQuil merely because it can build the same gates.

It is also a poor fit for teams that require offline operation but cannot package or operate native quilc and QVM binaries. The container files provide a route to include these components, but that adds infrastructure work. The external services have their own ports, versions, and startup commands. PyQuil does not turn them into a self-contained local runtime.

Cloud execution presents another boundary. QPU use depends on Quantum Cloud Services access, and the README does not specify authentication or account provisioning. A team evaluating production QPU execution should not treat the local Bell-state example as evidence that it can schedule and execute on real processors. It demonstrates program construction and a simulator client, not an end-to-end production deployment.

PyQuil compared with direct service operation

The closest alternative is to work directly with quilc, the QVM, or another quantum programming library instead of using PyQuil's Python representation. The difference is not that the underlying compilation or simulation engines disappear. Those engines remain part of the Forest stack. PyQuil adds a Python API for constructing Quil programs, declaring classical registers, applying gate constructors, requesting a QVM client, and reading returned register data.

For a Rigetti-oriented Python application, that layer removes the need to assemble the example's Quil-oriented operations manually in Python code. For an application already standardized on a different quantum SDK, adopting PyQuil means accepting its `Program` model, its Forest configuration, and its service client behavior. The choice should therefore follow the required execution backend and program representation, not a general preference for Python.

The repository also makes a useful comparison point for containerized development. Its `Dockerfile` copies `quilc` and `qvm` binaries from separate images, installs a pinned PyQuil version, and starts both through `entrypoint.sh`. That approach is more involved than installing only the Python package, but it aligns the service binaries with the intended Forest environment. It does not remove the need to understand which service each `get_qc` environment requires.

Editorial conclusion

PyQuil is appropriate for Python developers who need an explicit Quil representation and work within the Forest SDK. It is a poor fit for users who need only a local quantum simulator or cannot operate quilc, the QVM, or Rigetti cloud services. Before adoption, verify Python compatibility, service availability, network configuration, and whether execution on Rigetti QPUs through Quantum Cloud Services matches the intended environment.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rigetti/pyquil on GitHub