Setup IBM’s Qiskit SDK

IBM’s Qiskit is a leading quantum Software Development Kit (SDK) used as a foundation, not just for use with IBM hardware, but for various other quantum computing hardware architectures as well. IBM already has excellent Qiskit tutorials available online for free. Our Qollab Qiskit guides take a specific, UV-based approach to managing Python projects. If you have not installed UV (or Python), take a look at our previous guide: Setup Python (and UV) on your machine. For a crash course in Python fundamentals, see our guide: Learn Python basics.

1. Create a new project

Create a project folder on your Desktop titled our-qollab. (The exact name and location of this folder doesn’t matter so much, as long as it’s easy for you to get to and work with.)

Initialize our app

Open a shell to your project’s folder and enter the following command:

uv init --app

This will initialize your new UV-managed project. The uv init command has two main modes: 1. Library mode (default): For building a script that is primarily intended to be a reusable package, imported by other applications. 2. Application mode (using the --app flag): For building a script that is intended to be executable on its own. The --app flag instructs UV to assume the app will be run via uv run ... or uv run python -m .... It’s not meant to be installed as a dependency, and entry points matter more than exports.

Select a Python version

We want to be selective about which Python version our application uses because Qiskit and its various packages have particular compatibility requirements, and sometimes lag behind the most recent Python release. As of this writing, Python 3.12 is a safe choice for use. Enter the following into your shell to install Python 3.12 (if not already available) and explitly pin it as the version required by our application.

uv python install 3.12
uv python pin 3.12

Pitfalls to avoid

Qiskit only supports CPython, and not PyPy. You can confirm your Python versions via uv by entering the following into your shell:

uv python list

If you’re upgrading across major Qiskit eras, don’t “upgrade in place” inside an old virtual environment. Instead, make a new virtual environment for each project using uv venv.

Create a virtual environment

Initializing a UV app will “lazily” create a virtual environment. That is, the virtual environment ought to create and activate on-demand when it is first needed. But out of precaution we’d like to manually do that now ourselves. Enter the following into your shell:

uv venv

At this point our shell may ask us to enter something similar the following in order to activate our virtual environment:

source .venv/bin/activate

2. Add Qiskit packages

Enter the following into your shell to install Qiskit’s core package:

uv add qiskit

Let’s confirm that Qiskit has installed correctly. Enter the following into your shell and it should respond with a Qiskit version number:

uv run python -c "import qiskit; print('Qiskit', qiskit.__version__)"

Our first Qiskit app is going to use a quantum simulator that runs on your local machine, as opposed to using a cloud-based simulator or actual quantum hardware. (Don’t worry, we’ll get to real quantum hardware soon enough.) Install Qiskit’s fast local simulator (Qiskit Aer) by entering the following into your shell:

uv add qiskit-aer

We can run a similiar sanity check for Aer as well:

uv run python -c "import qiskit_aer; print('Qiskit Aer', qiskit_aer.__version__)"

3. Run a local simulation

Now that we’ve installed some Qiskit packages, let’s put them to use. Open up your project’s main.py Python script with your favorite text editor. Replace its contents with the following, and save it to disk:

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

def main():
    qc = QuantumCircuit(2)
    qc.h(0)
    qc.cx(0, 1)
    qc.measure_all()

    sim = AerSimulator()
    result = sim.run(qc, shots=1000).result()
    counts = result.get_counts()
    print("Counts:", counts)

if __name__ == "__main__":
    main()

This Python script imports Qiskit and Qiskit’s “Aer” local simulator. The command QuantumCircuit(2) creates a quantum circuit composed of two qubit registers, both initialized to a | 0 ⟩ (“ket zero”) state. It then places a Hadamard gate onto register 0, flipping that qubit into superposition. Next, it places a CNOT gate across the two registers, using register 0 as the control qubit and register 1 as the target qubit. This creates a Bell state, distributing register 0’s superposition across the two qubits, entangling them. Finally, we measure both qubit registers, collapsing the distributed superposition into a definitive value. The two possible measured values are | 00 ⟩ and | 11 ⟩ , each with a 50% probabilty of occurrence. This simulation is run 1,000 times (shots=1000) and the results of these “shots” and printed to the command line.

Execute this new main.py quantum script by entering the following into your shell:

uv run main.py

It will respond with output similar to the following:

Counts: {'00': 517, '11': 483}

Congratulations. You’ve just executed an incredibly convoluted coin-flip routine!

Coming soon

Stay tuned for our guide to running quantum simulations in the cloud, performing operations on actual quantum hardware, and making use of IonQ hardware architectures.