Lesson 3: Installing Qiskit

H Hannan

What is Qiskit
Back to The Qiskit Home Page

This step-by-step guide will cover everything you need to know to install Qiskit locally so you can start experimenting.

We will walk through key prerequisites, installation best practices for different systems, setting up virtual environments, verification, and solutions for common issues. Follow along and you’ll soon have access to one of the top full-stack quantum platforms.

Pre-requisites for Installing Qiskit

Before installing Qiskit itself, we must ensure the supporting software stack is in place. Qiskit’s core is written in Python, so we need an appropriate environment. Required elements include:

Python Interpreter

Since Qiskit consists of Python code accessing fast C++ simulators, we need an appropriate Python distribution. We recommend the latest stable Python 3.8 or higher which can run on all major operating systems. Modern interpreters include crucial optimizations for scientific computing.

Dont Have Python Installed? Learn How To Install It Here.

Python Package Manager

We also need a Python package manager to streamline adding Qiskit to environments and manage dependencies cleanly. The de facto standard choice is Pip, which ships with most Python 3 distributions. For system-level installs, ensure you have an up-to-date copy of pip3 (for Python 3 packages) or alternatively pip (to default to the active Python).

Operating System Support

Thanks to Python’s cross-platform pedigree, Qiskit supports installation on:

  • Windows 7 or higher
  • macOS 10.15 Catalina or higher
  • Most common Linux distros like CentOS, Ubuntu and Fedora released since 2015

If you want to access quantum devices, an internet connection is necessary too. But simulation and algorithm development can be done completely offline. With these foundational items fulfilled, we can move on to the main event.

Step-by-Step Qiskit Installation Guide

We’ll first explore the base Qiskit install which offers the most stable core toolkit. Just need certain elements? Skip ahead to the modular section fitting your use case. Let’s dive in:

  1. Open a terminal (Linux/macOS) or command prompt (Windows). Activate your Python environment if not already enabled.
  2. Upgrade pip to ensure you have the latest software and security patches:
pip install --upgrade pip
  1. Install the core Qiskit metapackage globally:
pip install qiskit

This special bundle intelligently grabs the necessary underlying Qiskit components – Terra, Aer, Ignis, Aqua and more – at compatible versions. It configures everything to integrate seamlessly in an opinionated stack curated by IBM Research and the community. The different components are as follows:

Terra: The foundation for composing and optimizing quantum circuits with a rich library of pre-built operations. Also interfaces with simulators.

Aer: Provides optimized C++ and Python simulators for rapidly prototyping algorithms and debugging code.

Ignis: Tools focused on quantum error characterization, mitigation techniques, and analyzing fidelity.

Aqua: Extensive libraries of common quantum algorithms across domains like optimization, finance, chemistry and AI.

Additional tailored modules also exist, like for finance and machine learning.

Based on your system, this process can take a few minutes to download dependencies, compile components from the source, and set up final integration.

  1. Validate your installation by opening a Python interpreter or script and importing Qiskit:
import qiskit

If no errors appear, you now have Qiskit ready for quantum programming! We’ll cover usage details next.

Modular & Custom Installation

For advanced needs, you can also install sub-elements a la carte via Pip:

pip install qiskit-terra
pip install qiskit-aer
pip install qiskit-ignis

Download only what you want to constrain resource usage. All modules integrate smoothly thanks to shared design paradigms when installed simultaneously.

Configure Environment Variables

You can optionally customize aspects like compilation parallelism for your system by exporting environment variables before installation:


See the full configuration guide to tweak elements as needed.

Now let’s look at how to supercharge Qiskit accessibility by leveraging virtual environments.

Setting Up a Qiskit Virtual Environment (Optional)

Python virtual environments enable isolating project dependencies from one another and your global Python install. This keeps everything tidy while giving the flexibility to try new packages safely. We’ll cover how to set one up to streamline your Qiskit experience.

Install VirtualEnv Tool

The most popular solution for virtual environments remains the aptly named VirtualEnv package. Install it via pip globally:

pip install virtualenv

This provides the virtualenv terminal command for subsequent steps.

Create a New Virtual Environment

Navigate to your desired working directory for quantum programming projects. A dedicated quantum folder is recommended.

Run the virtualenv command with a custom environment name – here we’ll use qiskitenv:

virtualenv qiskitenv

This creates a new folder qiskitenv containing an isolated Python interpreter and site libraries directory for arbitrary packages.

Activate Virtual Environment

Activate or “enter” the environment to have all Python commands target it instead of globally:

On Windows:


On Linux/macOS:

source qiskitenv/bin/activate

Your terminal prompt will prepend the virtual environment name reminding it is active.

Install Qiskit Within the Environment

Now simply install Qiskit as normal while the environment is active:

pip install qiskit

The qiskitenv instance maintains its own isolated copy of Qiskit without polluting global Python. You can also install Jupyter and IQX easily here for a dedicated quantum notebook server.

Deactivate When Done

When ready to take a break from quantum computing and return to your global Python (with all its other packages), simply run:

source qiskitenv/bin/deactivate

On Windows drop the source prefix. Custom tools or Python GUI clients handle activation automatically when opening projects within the environment directory too.

Verifying Qiskit Installation

With Qiskit installed via your preferred method, let’s validate everything works as expected.

Open a Python interpreter or script and import core elements:

import qiskit
from qiskit import execute, Aer
from qiskit.visualization import plot_histogram

If no errors, you can create a simple circuit and use built-in simulators to run:

backend = Aer.get_backend('qasm_simulator')
circuit = transpile(QuantumCircuit(2), backend)
job = execute(circuit, backend)

This will render a visualization confirming installation and connectivity to simulators work correctly.

You can also test hardware access if entitlements are enabled:

from qiskit import IBMQ
provider = IBMQ.load_account()
backend = provider.get_backend('ibmq_quito')

With real systems, use short circuits to minimize queue latency. But simulation combined with Python imports will validate software functionality quickly.

Troubleshooting Common Qiskit Installation Issues

Despite the simplicity, occasionally issues arise with Qiskit installation. Let’s review some common pitfalls and mitigations.

Python Environment Confusion

If another Python version is active over intended 3.X distribution, pip may install to unintended system paths. Double-check the Python –version and consider leveraging virtual environments to isolate Qiskit as shown earlier.

Dependency & Compiler Errors

Certain C++ compilers or Python packages may be missing. Check pip install logs for missing prerequisites. On Linux, often just installing build-essential meta-package resolves this. Upgrading pip and setuptools helps too.

Platform Differences

Qiskit binaries for some elements like qiskit-aer are platform specific. Errors compiling or running simulations likely indicates a mismatch. Ensure you install only for your operating system or leverage containers for full reproducibility.

Outdated Packages

As a rapidly evolving ecosystem, keeping Qiskit modules like Terra, Aer and Ignis in sync is crucial. Always reinstall qiskit metapackage to implicitly coordinate versions rather than manually updating only parts.

Network Connectivity

If backend connections or API requests fail, validate that internet access is present and your Python environment has SSL/TLS module enabled. Check with other tools to isolate issues stemming from proxies or firewalls too.

Still Stuck?

For any other exotic issues reaching the IBM quantum team and community through GitHub issues or Stack Overflow is wise. Chances are others have helpful insights to get you unblocked quickly.

Next Steps with Qiskit

Now that you have Qiskit installed and validated, you are ready to start quantum computing locally and tap into demonstrations and tutorials using real code. Experiment with algorithms, develop simulations, and research novel quantum applications.

The Qiskit documentation offers rich examples for next steps tailored to your background – whether new to quantum or an experienced practitioner. There is no substitute for hands-on programming experience accelerating up the learning curve. With your technical environment setup, you now have the tooling to build and create using qubits just like classical bits.

The future of quantum computing is bright, and installing foundational SDKs like Qiskit into your skillset is how to participate. This post should provide all the detail needed to get started on Windows, macOS or Linux systems tailored to your use case. Here’s to beginning your quantum

Leave a Comment