Python samples demonstrating quantum computing on IonQ's platform using popular quantum libraries. A great starting point for exploring quantum computation.
For advanced examples implementing specific algorithms, check out the ionq-samples organization.
- Python 3.10-3.13
- IonQ API key (set as
IONQ_API_KEYenvironment variable)
Using pip:
pip install -e .Using uv (faster):
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -e .Using conda:
conda env create -f environment.ymlJupyter:
jupyter notebookVS Code:
Open any .ipynb file and select a Python kernel.
Cloud:
Click the 
Run in a containerized environment:
# Build
docker build --platform=linux/x86_64 -t ionq-notebooks .
# Run
docker run -p 8888:8888 -e IONQ_API_KEY="your_api_key" ionq-notebooksOpen http://localhost:8888 in your browser.
# All tests
pytest tests/
# Parallel execution
pytest -n auto tests/
# Specific notebook
pytest tests/test_notebooks.py::test_notebook_execution[qiskit.ipynb]
# With custom timeout
NBEXEC_TIMEOUT_SECONDS=900 pytest tests/GitHub Actions automatically tests all notebooks on every push.
This repository includes a pre-commit Git hook to automatically clean Jupyter notebook metadata using nb-clean before committing. This helps reduce unnecessary noise in commits and avoid merge conflicts.
To enable this, run the following command in your terminal from the root of this repository:
git config core.hooksPath .githooksNote: If uv is not installed, the hook will issue a warning and skip the cleaning process.
Submit issues or PRs in this repository, or contact support@ionq.com.