Get started with the Azure Quantum Development Kit (Modern QDK)

Learn about the different environment options available to develop quantum computing using the Azure Quantum service. Every environment uses the Azure Quantum Development Kit (Modern 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.

Running quantum programs

Azure Quantum offers several environments to start exploring quantum programming.

  Azure Quantum Website Visual Studio Code (Web) Azure portal Visual Studio Code
Built-in Q# support *
Jupyter notebooks  
Resource Estimator  
QPU access  
(with Azure subscription)

(with Azure subscription)

(with Azure subscription)
Python support    
Qiskit and Cirq support    
Integrated Hybrid      
(with Classic QDK)
Local setup      

* VS Code and VS Code (Web) provide rich Q# language support such as IntelliSense and debugging.

The Azure Quantum website

On the Azure Quantum website, you can write and run Q# code right in your browser in the online code editor and open your code directly in VS Code on the Web with one click - no installation or Azure account required. Write your own Q# code, use the built-in samples, or prompt the Copilot in Azure Quantum to create Q# code. For more information, see Explore Azure Quantum.

The Azure Quantum portal

The Azure Quantum portal provides a no-install development environment where you can create, upload, store, and run your quantum code in Jupyter Notebooks on a quantum simulator or quantum hardware targets. A gallery of sample Jupyter Notebooks is provided to get you started with quantum programming in Q#, Python, and running Qiskit and Cirq circuits. 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.

Visual Studio Code

The Modern QDK VS Code extension is the latest version of the Q# language and quantum development tools. With a smaller footprint and faster performance, it features a streamlined installation, language improvements, integrated Python, Jupyter Notebook, and Qiskit support, integrated Azure connectivity for submitting jobs to quantum hardware, debugger support, and improved syntax highlighting and error messages. The Modern QDK is platform independent, running on Windows, Mac, Linux, and the web. For set up information, see Installing the Modern QDK.

Visual Studio Code on the Web

VS Code on the Web is a free resource that offers the same performance, Azure connectivity, and Q# language features (such as syntax highlighting, IntelliSense, and debugging) as the installed version of VS Code, minus some of the extended features (see the comparison table for details). vscode.dev/quantum offers a preconfigured quantum environment, and vscode.dev/quantum/playground/ offers a preconfigured quantum environment, sample code, and learning content to get you up and running.

Note

If you already have a Python and Jupyter Notebook environment configured on your machine, you can connect to your Jupyter server from VS Code on the Web and run Q# notebooks. For more information, see Connecting to a remote Jupyter server from vscode.dev.

Installing the Modern QDK on VS Code

Note

To avoid possible conflicts of package version, be sure to follow the uninstall instructions in step 2.

To install the Modern QDK:

  1. In VS Code, disable or uninstall the Microsoft Quantum Development Kit extension.
  2. Run python -m pip uninstall qsharp qsharp-core qsharp-chemistry azure-quantum
  3. If needed, install the latest version of VS Code or open VS Code on the Web.
  4. Install the Azure Quantum Development Kit extension.

That's it. You can now write, debug, and run Q# programs against the built-in quantum simulator, or if you already have an Azure account, connect and submit Q# programs to quantum hardware, all from VS Code.

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

Add support for Python and Jupyter Notebooks

With added Python support, you can embed or call Q# code from your Python programs or Jupyter Notebooks and run them on the built-in quantum simulator, or connect to your Azure workspace and submit your jobs to quantum hardware, all from VS Code.

Prerequisites

  • A Python environment (3.9 or greater, 3.11 recommended) with Python and Pip installed.
  • VS Code with the Modern QDK extension installed.

To add Python and Jupyter Notebook support:

  1. Install the Python and Jupyter extensions for VS Code.

  2. Install the qsharp and azure-quantum packages:

    python -m pip install qsharp azure-quantum
    
  3. For Qiskit or Cirq support, install azure-quantum using the [qiskit] or [cirq] parameters:

    Important

    If you are updating from a previous Qiskit environment, see Update the azure-quantum package with Qiskit support.

    python -m pip install azure-quantum[qiskit]
    or
    python -m pip install azure-quantum[cirq]
    or
    python -m pip install azure-quantum[qiskit, cirq]
    
  4. Install optional Python packages you may need to display results and work in Jupyter Notebooks:

    python -m pip install ipykernel ipympl jupyterlab
    

To test your setup, see Submit Q# jobs with Python or Submit Q# jobs with Jupyter Notebooks.

Add support for Azure CLI

The Azure CLI is an optional method for submitting quantum jobs using a terminal window in VS Code.

  1. Install the Azure CLI.

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

    az extension add \
        --upgrade \
        -n quantum
    

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

Compatibility with the Classic QDK

For more information, see What's new in the Modern QDK.

  • The Modern QDK is not fully backwards compatible with the previous Classic QDK. Not all APIs have been ported, and existing project files aren't recognized. Your current programs and projects could require significant changes and updates. For more information, see Migrating your code to the Modern QDK and What's new in the Modern QDK.
  • The Modern QDK extension and the previous Classic QDK extension can be installed in VS Code at the same time, but both cannot be enabled at the same time. If you are working exclusively with the Modern QDK, or if your programs require features not yet supported in the Modern QDK (such as hybrid quantum computing), only enable one extension at a time. For more information, see Continue working in the Classic QDK.
  • The Azure Quantum website and Azure Quantum portal environments use the Modern QDK exclusively.

Continue working in the Classic QDK

Some features, such as hybrid computing, are not yet supported in the Modern QDK. To continue using the Classic QDK environment for this functionality:

  1. If you have installed any of the Modern QDK components:
    1. In VS Code, disable or uninstall the Azure Quantum Development Kit extension.
    2. Run python -m pip uninstall qsharp
  2. In VS Code, enable or install the Microsoft Quantum Development Kit extension.
  3. Run python -m pip install qsharp<1.0.

Using the Azure portal: