Edit

Set up the Quantum Development Kit

  • Article

Note

Now available! The Azure Quantum Development Kit (QDK) Preview is the latest preview of the Q# development kit, and is available as an extension for Visual Studio Code. For more information, see the Modern QDK.

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 Azure Quantum website

With the Azure Quantum website, you can run Q# code in your browser with no setup required. For more information, see Explore Azure Quantum.

The Azure Quantum Development Kit (Modern QDK) Preview

The Modern QDK is a preview of the next version of the Q# language and development tools. With a smaller footprint and faster performance, it is tightly integrated with Visual Studio Code, it features one-step installation, language improvements, integrated Python and Jupyter Notebook support, new syntax highlighting, debugger support, error messages, and integrated Azure connectivity. By eliminating the dependencies of the Microsoft QDK, it is now truly platform independent, running on Windows, Mac, Linux, and the web.

download icon.
Download the Modern QDK

Warning

The Modern QDK preview is not fully backwards-compatible with the Classic QDK. Not all APIs have been ported, and existing project files aren't recognized. Your current programs and projects may require significant changes and updates.

To help you get started, a new set of samples specifically for the Modern QDK is available on the QSharp GitHub samples page.

For installation steps and a walkthrough of the new features, see the Installation page.

Note

The Modern QDK extension and the Classic QDK extension can both be installed in VS Code at the same time, but cannot be enabled at the same time. If you are working exclusively with the Modern QDK, or if your programs require features not supported yet in the Modern QDK, only enable one extension at a time.

What's new

Classic QDK Modern QDK
Requires .NET SDK No .NET dependency
Azure job integration through Azure CLI Azure job integration built-in to VS Code Explorer
No native debugging Integrated Q# debugger:
- Breakpoints
- Stepping into code
- Error checking in Q# source files
- Auto-completion
- Go to definition
- Function signature help
- Hover definitions
- Inspect values for quantum and classic variables
N/A Improved compiler error messages
N/A Improved language syntax
Multiple in-memory simulators Integrated sparse state simulator
Python and Jupyter Notebook support Integrated Python and Jupyter Notebook support
Multiple files At this time, the Modern QDK supports single Q# files only
Hybrid computing The Modern QDK does not yet support Batch, Interactive, and Integrated computing
Visual Studio support The Modern QDK will not support the Visual Studio IDE environment

For an updated list of Modern QDK features and changes from the Classic QDK, see the QSharp GitHub Wiki.

The Microsoft Quantum Development Kit (QDK)

The QDK provides:

  • Python packages to submit Qiskit, Cirq and Q# applications 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:

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.

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.

Portal installation options

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 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.

Screenshot of Azure portal showing how to find a link to a local configuration install guide.

Prerequisite

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:

  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.

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.

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.

  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.

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.

Use the QDK with GitHub Codespaces

GitHub Codespaces is a secure and configurable cloud-powered development environment. There is no local setup involved and the default compute instances are available free of charge, with options to increase the number of cores and the amount of RAM and storage.

Prerequisites

  • You will need a GitHub account (https://github.com/join) and access to the GitHub repository you want to work with.

Configuring your codespace

  1. From the root page of your repository, select Code > Codespaces > ... > Configure dev container.

  2. Replace the contents of the default devcontainer.json file with the following:

    {    
    "image": "mcr.microsoft.com/devcontainers/universal:2",
    "extensions": [
        "quantum.quantum-devkit-vscode",
        "ms-vscode.csharp",
        "editorconfig.editorconfig",
        "ms-python.python"
    ],
    "features": {
        "ghcr.io/devcontainers/features/python:1": {
        "version": "3.11.2",
        "installJupyterlab": "true"
        },
    "ghcr.io/devcontainers/features/azure-cli:1": {
        "extensions": "quantum"
        }
    },
    "postCreateCommand": "wget https://dot.net/v1/dotnet-install.sh && chmod +x dotnet-install.sh && ./dotnet-install.sh -c 6.0 && rm dotnet-install.sh && pip install azure-quantum[qiskit]"
}

    Tip

    You can customize your GitHub Codespaces at any time after setup. For more information, see Introduction to dev containers.

  3. Select Start commit > Commit directly to the main branch, then select Commit new file. GitHub creates a folder named .devcontainer with your new configuration file.

  4. If you want to create your codespace on a branch other than main, select that branch.

  5. Select Code > Codespaces > Create codespace on main (or your preferred branch). The initial setup may take 5-10 minutes.

  6. When the setup is complete, the codespace development shell opens. Wait for the postCreateCommand to complete.

  7. Enable web-based authentication:

    1. From a command prompt, run az login --use-device-code.
    2. Copy the device code and use it to authenticate at https://microsoft.com/devicelogin.

Additional configurations (optional)

  • Codespace names - Codespaces uses a randomly generated name when it creates a new codespace. You can rename a codespace to a friendlier name by selecting Code > Codespaces > ... > Rename next to the codespace name.
  • Compute resources - By default, each codespace is created with a minimal compute setup. You can increase the compute resources by selecting Code > Codespaces > ... > Change machine type next to the codespace name. For more information about fees for additional compute usage, see Pricing for paid usage.
  • Billing configuration - By default, usage costs for GitHub Codespaces are automatically billed to the GitHub account that created the codespace. Optionally, you can connect an Azure subscription to pay for GitHub Codespaces and other GitHub services. For more information and requirements, see Connecting an Azure subscription to your enterprise.

Next steps

Using the Azure portal:

Using your local environment: