Edit

Connect to your Azure Quantum workspace with the QDK or Azure CLI

If you have an Azure Quantum workspace, you can use the qdk.azure Python module the connect to the workspace and submit your code to run on Azure Quantum. The qdk.azure module provides a Workspace class that represents an Azure Quantum workspace.

Warning

Starting January 11, 2027, Azure Quantum requires users in a Quantum workspace to have the Quantum Workspace Data Reader or Quantum Workspace Data Contributor role to view job results. The Quantum Workspace Data Contributor role will be required to submit jobs. To avoid interruptions to your Azure Quantum workflows, assign these roles to the appropriate users before the deadline. For more information, see Assign data access roles for users in the workspace.

Prerequisites

To connect to your workspace with the qdk.azure module, you need:

  • An Azure account with an active subscription. If you don't have an Azure account, register for free and sign up for a pay-as-you-go subscription.

  • An Azure Quantum workspace. If you don't have a workspace, see Create an Azure Quantum workspace.

  • The latest version of the qdk Python package with the azure extra.

    pip install --upgrade "qdk[azure]"
    

If you use the Azure CLI, update to the latest version. For installation instructions, see:

Connect with an Azure account

Use an Azure account to connect to your Azure Quantum workspace with the Microsoft Quantum Development Kit (QDK) extension in Visual Studio Code (VS Code).

  1. Open VS Code.
  2. Select View > Command Palette.
  3. Enter and select QDK: Connect to an Azure Quantum workspace.
  4. Choose Azure account.
  5. When a VS Code message says that QDK wants to sign in, select Allow.
  6. Select the account to use.
  7. Select a tenant and subscription.

To view your Azure Quantum workspace, select the Microsoft Quantum icon on the Activity Bar.

Screenshot of the Microsoft Quantum panel icon on the Activity Bar in Visual Studio Code.

Connect with a connection string

Note

Connection strings are less secure than an Azure account.

Use a connection string to specify the connection parameters for an Azure Quantum workspace. Connection strings are useful when:

  • You want to share access to your workspace with others who don't have an Azure account.
  • You want to share access to your workspace with others for a limited time.
  • You can't use Microsoft Entra ID because of company policies.

Tip

Every Azure Quantum workspace has a primary key and a secondary key, and each key has its own connection string. To let others use your workspace, share the secondary key and keep the primary key for your own services. That way, you can replace the secondary key without causing downtime in your services. For more information about sharing access to your workspace, see Share your workspace access.

Copy the connection string

  1. Sign in to the Azure portal.
  2. Go to your Azure Quantum workspace.
  3. In the workspace panel, expand the Operations dropdown and select Access Keys.
  4. If the Access Keys slider is set to Disabled, set it to Enabled.
  5. Select the Copy icon for the connection string that you want to copy. You can choose either the primary or secondary connection string.

Warning

Storing your account access keys or connection strings in clear text is a security risk. Store your account keys in an encrypted format, or migrate your apps to use Microsoft Entra authorization for your Azure Quantum workspace.

Use the connection string to access your Azure Quantum workspace

Use the connection string you copied to connect to your Azure Quantum workspace with the qdk.azure module or the QDK extension in VS Code.

To connect to your Azure Quantum workspace, choose one of the following methods.

  • Use the from_connection_string function to create a Workspace object.

    from qdk.azure import Workspace 
    
    connection_string = "<ConnectionString>" # Replace with your connection string
    workspace = Workspace.from_connection_string(connection_string) 
    
    print(workspace.get_targets())
    
  • Store your connection string in an environment variable.

    import os
    from qdk.azure import Workspace 
    
    connection_string = "<ConnectionString>" # Replace with your connection string
    os.environ["AZURE_QUANTUM_CONNECTION_STRING"] = connection_string 
    
    workspace = Workspace() 
    print(workspace.get_targets()) 
    

For more information about how to work with keys, see Authenticate in your workspace using an access key.

Important

If you disable access keys for your workspace, you can't connect with connection strings. Use workspace parameters instead.

Connect to your workspace with workspace parameters

Every Azure Quantum workspace has a unique set of parameters that you use to connect to the workspace.

Parameter Description Use when you connect with
subscription_id The Azure subscription ID. Azure CLI
resource_group The Azure resource group name. Azure CLI
name The name of your Azure Quantum workspace. Azure CLI
resource_id The Azure resource ID of the Azure Quantum workspace. Python

To find your workspace parameters, follow these steps:

  1. Sign in to the Azure portal.
  2. Go to your Azure Quantum workspace.
  3. From your workspace panel, select Overview.
  4. Expand the Essentials dropdown.
  5. Copy the parameters from their corresponding fields.

Note

Ensure that you sign in to the correct tenant before you connect to your workspace. For more information about tenants, see How to manage Azure subscriptions with the Azure CLI.

Use workspace parameters to connect to your Azure Quantum workspace

To stay signed in when you run your Python scripts, open a terminal and run the following Azure CLI command to set the subscription for your workspace. Replace <subscriptionId> with your subscription ID.

az account set --subscription <subscriptionId>

Use your workspace parameters to connect to your Azure Quantum workspace through the qdk.azure module or the Azure CLI.

To connect to your Azure Quantum workspace, choose one of the following options.

  • Specify the resource ID (recommended):

    from qdk.azure import Workspace 
    
    workspace = Workspace(resource_id="") # Add the resource ID of your workspace
    
  • Specify the subscription ID, resource group, and workspace name:

    from qdk.azure import Workspace 
    
    workspace = Workspace(  
        subscription_id="", # Add the subscription ID of your workspace
        resource_group="", # Add the resource group of your workspace
        name="" # Add the name of your workspace
        )
    
  • Specify only the workspace name. This option might fail if you have multiple workspaces with the same name in the same tenant.

    from qdk.azure import Workspace 
    workspace = Workspace(name="") # Add the name of your workspace