Set up the Quantum Development Kit

Learn about the different environment options available to develop quantum computing and optimization applications using the Azure Quantum service.

Every environment uses the Quantum Development Kit (QDK), an open-source set of tools that includes the quantum programming language Q# and accompanying libraries. With the QDK, you can develop quantum computing applications using different IDEs and languages, and run them on quantum simulators or quantum hardware using Azure Quantum.

The QDK provides:

• Python packages to submit Qiskit and Cirq applications, Q# applications, or optimization problems (QIO) to the Azure Quantum service
• The Q# programming language and libraries
• The IQ# kernel for running Q# on Jupyter Notebooks
• Extensions for Visual Studio Code and Visual Studio
• Azure CLI extension to manage the Azure Quantum service and submit Q# applications
• APIs for using Python and .NET languages (C#, F#, and VB.NET) with Q#

Choose from several development environment options:

• Use a Jupyter Notebook in the Azure Quantum portal and submit jobs to Azure Quantum (recommended)
• Use your preferred IDE and language locally and submit jobs to Azure Quantum
• Use a pre-configured Docker image

Jupyter Notebooks

Jupyter Notebooks allow running code in-place alongside instructions, notes, and other content. This environment is ideal for writing Python and Q# code with embedded explanations or creating quantum computing interactive tutorials. The Jupyter Notebooks environment is built-in to the Azure Quantum portal or can be installed on your local computer.

Note

Accessing remote quantum hardware and submitting jobs to the Azure Quantum service requires an Azure account with an active subscription. You can create an account for free.

Use a Jupyter Notebook in the Azure Quantum portal and submit jobs to Azure Quantum (recommended)

The Azure Quantum portal provides a built-in development environment where you can create, upload, store, and run your quantum code in Jupyter Notebooks, using both quantum simulators and quantum hardware targets. A gallery of sample Jupyter Notebooks is provided to get you started with quantum programming in Q#, running Qiskit and Cirq circuits, or submitting optimization problems. From the portal, you can also manage quantum workspaces, jobs, activity, credits and usage, and access control. To get started, see Create an Azure Quantum workspace.

Tip

First-time users automatically get free $500 (USD) Azure Quantum Credits for use with each participating quantum hardware provider. If you have consumed all the credits and you need more, you can apply to the Azure Quantum Credits program.

Use your preferred IDE and language locally and submit jobs to Azure Quantum

Installing the QDK on your local computer provides support for Jupyter Notebooks, Python, and Q#, along with extensions for Visual Studio Code and Visual Studio. Develop quantum computing applications in your preferred IDE and language and run them on quantum simulators, quantum hardware, or optimization solvers using the Azure Quantum service.

Some scenarios where you may prefer a local environment:

• You have a customized environment or preferred tools that are not available online.
• You require source control on your project.
• You are working with a multi-file project.

Note

Accessing remote quantum hardware and submitting jobs to the Azure Quantum service requires an Azure account with an active subscription. You can create an account for free.

Select your preferred IDE:

• Use Q# and Python with Visual Studio Code or Visual Studio
• Use Python with Qiskit, Cirq, or Azure Quantum optimization solvers
• Use Q# and Python with Jupyter Notebooks
• Use the QDK with a pre-configured Docker image

Use Q# and Python with Visual Studio and Visual Studio Code

While you can build Q# applications in any IDE, we recommend using Visual Studio Code (VS Code) or Visual Studio IDE for developing your Q# applications. Developing in either of these environments leverages the rich functionality of the Quantum Development Kit (QDK) extension, which includes submitting quantum jobs via the Azure CLI, warnings, syntax highlighting, project templates, and more.

Alternatively, you can go to Azure portal and under your Quantum workspace > Overview, you'll find a link to local configuration install guide at the bottom of the page.

Prerequisite

• .NET SDK 6.0

Azure CLI

The Azure CLI is the preferred method for submitting quantum jobs using a terminal window in VS Code or Visual Studio.

• Install the Azure CLI.

• Install the latest Azure CLI quantum extension. Open a command prompt and run the following command:

  az extension add --upgrade -n quantum
  
  

Configure the QDK for your preferred environment from one of the following options:

VS Code

1. Download and install VS Code 1.52.0 or greater (Windows, Linux and Mac).
2. Install the QDK for VS Code.

Note

If you are a Arm-based Mac user, make sure you install .NET SDK 6.0 or greater, as older versions are not supported on this architecture.

Visual Studio (Windows only)

1. Download and install Visual Studio 17.0 or greater, with the .NET Core cross-platform development workload enabled.
2. Download and install the QDK.

Note

Although there is Visual Studio for Mac, the QDK extension is only compatible with Visual Studio for Windows.

To test your environment, see Submit Q# jobs to Azure Quantum.

Use Python with Qiskit or Cirq, or Azure Quantum optimization solvers

You can use the azure-quantum Python package to submit and run Qiskit or Cirq jobs, or submit quantum-inspired optimization jobs to the Azure Quantum optimization solvers.

To install the azure-quantum Python package

1. Install Python 3.9 or later if you haven't already.

2. Install PIP and ensure you have version 19.2 or higher.

3. Install the azure-quantum python package. Use the --upgrade flag to make sure to get the latest version.

   To install the azure-quantum package without any optional dependencies, run:

   pip install --upgrade azure-quantum
   

   To install the optional dependencies required for submitting Qiskit programs, install using the [qiskit] tag:

   pip install --upgrade azure-quantum[qiskit]
   

   To install the optional dependencies required for submitting Cirq programs, install using the [cirq] tag:

   pip install --upgrade azure-quantum[cirq]
   

To test your environment, see Create a quantum-based random number generator or Submit a circuit with Qiskit.

Use Q# and Python with Jupyter Notebooks

All the necessary components for a Juptyer Notebooks environment can be set up with a single conda installation.

Note

While a conda installion is recommended, if you prefer not to install conda, you can also set up your environment using the .NET CLI.

Install using conda (recommended)

1. Install Miniconda or Anaconda. Consult their installation guide if you are unsure about any steps. Note: 64-bit installation required.

2. Initialize conda for your preferred shell with the conda init initialization command. The steps below are tailored to your operating system:

   (Windows) Open an Anaconda Prompt by searching for it in the start menu. Then run the initialization command for your shell, for example, conda init powershell cmd.exe will set up both the Windows PowerShell and command prompt for you. You can then close this prompt.

   Important

   To work with PowerShell, conda will configure a startup script to run whenever you launch a PowerShell instance. By default, the script's execution will be blocked on Windows, and requires modifying the PowerShell execution policy with the following command (executed from within PowerShell):

   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
   

   (Linux) If haven't done so during installation, you can still initialize conda now. Open a terminal and navigate to the bin directory inside your selected install location (for example, /home/ubuntu/miniconda3/bin). Then run the appropriate command for your shell, for example,./conda init bash. Close your terminal for the changes to take effect.

3. From a new terminal, create and activate a new conda environment named qsharp-env with the required packages (including Jupyter Notebook and IQ#) by running the following commands:

   conda create -n qsharp-env -c microsoft qsharp notebook
   
   conda activate qsharp-env
   

4. Finally, run python -c "import qsharp" to verify your installation and populate your local package cache with all required QDK components.

Install using .NET CLI and pip (advanced)

1. Prerequisites:

   • Python 3.9 or later
   • The PIP Python package manager
   • .NET SDK 6.0

2. Install the qsharp package, a Python package that enables interop between Q# and Python.

   pip install qsharp
   

3. Install IQ#, a kernel used by Jupyter and Python that provides the core functionality for compiling and running Q# operations.

   dotnet tool install -g Microsoft.Quantum.IQSharp
   dotnet iqsharp install
   

   Note

   If you encounter a permission error in Linux, install the IQ# kernel in user mode instead with dotnet iqsharp install --user.

   Note

   If you encounter an error and you just installed .NET, you won't be able to run the dotnet iqsharp install command immediately. Instead, under Windows, open a new terminal window and try again. Under Linux, log out of your session and log back in to try again. If this still doesn't work, try locating the installed dotnet-iqsharp tool (on Windows, dotnet-iqsharp.exe) and running:

   /path/to/dotnet-iqsharp install --user --path-to-tool="/path/to/dotnet-iqsharp"
   

   where /path/to/dotnet-iqsharp should be replaced by the absolute path to the dotnet-iqsharp tool in your file system. Typically this will be under .dotnet/tools in your user profile folder.

You now have both the qsharp Python package and the IQ# kernel for Jupyter, allowing you to compile and run Q# operations from Python and Q# Jupyter Notebooks. To test your environment, see Submit a quantum program.

Use the QDK with a pre-configured Docker image (advanced)

You can use our QDK Docker image in your local Docker installation or in the cloud via any service that supports Docker images, such as ACI.

You can download the IQ# Docker image from https://github.com/microsoft/iqsharp/#using-iq-as-a-container.

You can also use Docker with a Visual Studio Code Remote Development Container to quickly define development environments. For more information about VS Code Development Containers, see https://github.com/microsoft/Quantum/tree/master/.devcontainer.

Next steps

Using the Azure portal:

• Run Jupyter notebooks on Azure Quantum
• Create and submit a Qiskit circuit to quantum hardware.
• Create and submit an optimization problem to Azure Quantum.

Using your local environment:

• Explore development with Q# and Python
• Create and submit an optimization problem to Azure Quantum.