Manage Azure Machine Learning workspaces in the portal or with the Python SDK (v2)

APPLIES TO: Python SDK azure-ai-ml v2 (current)

In this article, you create, view, and delete Azure Machine Learning workspaces for Azure Machine Learning, using the Azure portal or the SDK for Python.

As your needs change or requirements for automation increase you can also manage workspaces using the CLI, Azure PowerShell, or via the VS Code extension.


  • An Azure subscription. If you don't have an Azure subscription, create a free account before you begin. Try the free or paid version of Azure Machine Learning today.
  • If using the Python SDK:
    1. Install the SDK v2.

    2. Install azure-identity: pip install azure-identity. If in a notebook cell, use %pip install azure-identity.

    3. Provide your subscription details

      # Enter details of your subscription
      subscription_id = "<SUBSCRIPTION_ID>"
      resource_group = "<RESOURCE_GROUP>"
    4. Get a handle to the subscription. ml_client is used in all the Python code in this article.

      # get a handle to the subscription
      from import MLClient
      from azure.identity import DefaultAzureCredential
      ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group)
      • (Optional) If you have multiple accounts, add the tenant ID of the Microsoft Entra ID you wish to use into the DefaultAzureCredential. Find your tenant ID from the Azure portal under Microsoft Entra ID, External Identities.

      • (Optional) If you're working on a sovereign cloud, specify the sovereign cloud to authenticate with into the DefaultAzureCredential..

        from azure.identity import AzureAuthorityHosts


  • When creating a new workspace, you can either automatically create services needed by the workspace or use existing services. If you want to use existing services from a different Azure subscription than the workspace, you must register the Azure Machine Learning namespace in the subscription that contains those services. For example, creating a workspace in subscription A that uses a storage account from subscription B, the Azure Machine Learning namespace must be registered in subscription B before you can use the storage account with the workspace.

    The resource provider for Azure Machine Learning is Microsoft.MachineLearningServices. For information on how to see if it is registered and how to register it, see the Azure resource providers and types article.


    This only applies to resources provided during workspace creation; Azure Storage Accounts, Azure Container Register, Azure Key Vault, and Application Insights.

  • When you use network isolation that is based on a workspace's managed virtual network with a deployment, you can use resources (Azure Container Registry (ACR), Storage account, Key Vault, and Application Insights) from a different resource group or subscription than that of your workspace. However, these resources must belong to the same tenant as your workspace. For limitations that apply to securing managed online endpoints using a workspace's managed virtual network, see Network isolation with managed online endpoints.

  • By default, creating a workspace also creates an Azure Container Registry (ACR). Since ACR doesn't currently support unicode characters in resource group names, use a resource group that doesn't contain these characters.

  • Azure Machine Learning doesn't support hierarchical namespace (Azure Data Lake Storage Gen2 feature) for the workspace's default storage account.


An Azure Application Insights instance is created when you create the workspace. You can delete the Application Insights instance after cluster creation if you want. Deleting it limits the information gathered from the workspace, and may make it more difficult to troubleshoot problems. If you delete the Application Insights instance created by the workspace, you cannot re-create it without deleting and recreating the workspace.

For more information on using this Application Insights instance, see Monitor and collect data from Machine Learning web service endpoints.

Create a workspace

You can create a workspace directly in Azure Machine Learning studio, with limited options available. Or use one of the following methods for more control of options.

APPLIES TO: Python SDK azure-ai-ml v2 (current)

  • Default specification. By default, dependent resources and the resource group are created automatically. This code creates a workspace named myworkspace and a resource group named myresourcegroup in eastus2.

    # Creating a unique workspace name with current datetime to avoid conflicts
    from import Workspace
    import datetime
    basic_workspace_name = "mlw-basic-prod-" +
    ws_basic = Workspace(
        display_name="Basic workspace-example",
        description="This example shows how to create a basic workspace",
    ws_basic = ml_client.workspaces.begin_create(ws_basic).result()
  • Use existing Azure resources. You can also create a workspace that uses existing Azure resources with the Azure resource ID format. Find the specific Azure resource IDs in the Azure portal or with the SDK. This example assumes that the resource group, storage account, key vault, App Insights, and container registry already exist.

    # Creating a unique workspace name with current datetime to avoid conflicts
    import datetime
    from import Workspace
    basic_ex_workspace_name = "mlw-basicex-prod-" +
    # Change the following variables to resource ids of your existing storage account, key vault, application insights
    # and container registry. Here we reuse the ones we just created for the basic workspace
    existing_storage_account = (
        # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT>"
    existing_container_registry = (
        # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<CONTAINER_REGISTRY>"
    existing_key_vault = (
        # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>"
    existing_application_insights = (
        # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.insights/components/<APP_INSIGHTS>"
    ws_with_existing_resources = Workspace(
        display_name="Bring your own dependent resources-example",
        description="This sample specifies a workspace configuration with existing dependent resources",
    ws_with_existing_resources = ml_client.begin_create_or_update(

For more information, see Workspace SDK reference.

If you have problems in accessing your subscription, see Set up authentication for Azure Machine Learning resources and workflows, and the Authentication in Azure Machine Learning notebook.



For more information on using a private endpoint and virtual network with your workspace, see Network isolation and privacy.

APPLIES TO: Python SDK azure-ai-ml v2 (current)

# Creating a unique workspace name with current datetime to avoid conflicts
import datetime
from import Workspace

basic_private_link_workspace_name = (
    "mlw-privatelink-prod-" +"%Y%m%d%H%M")

ws_private = Workspace(
    display_name="Private Link endpoint workspace-example",
    description="When using private link, you must set the image_build_compute property to a cluster name to use for Docker image environment building. You can also specify whether the workspace should be accessible over the internet.",


This class requires an existing virtual network.


By default, metadata for the workspace is stored in an Azure Cosmos DB instance that Microsoft maintains. This data is encrypted using Microsoft-managed keys.

To limit the data that Microsoft collects on your workspace, select High business impact workspace in the portal, or set hbi_workspace=true in Python. For more information on this setting, see Encryption at rest.


Selecting high business impact can only be done when creating a workspace. You cannot change this setting after workspace creation.

Use your own data encryption key

You can provide your own key for data encryption. Doing so creates the Azure Cosmos DB instance that stores metadata in your Azure subscription. For more information, see Customer-managed keys.

Use the following steps to provide your own key:


Before following these steps, you must first perform the following actions:

Follow the steps in Configure customer-managed keys to:

  • Register the Azure Cosmos DB provider
  • Create and configure an Azure Key Vault
  • Generate a key

APPLIES TO: Python SDK azure-ai-ml v2 (current)

from import Workspace, CustomerManagedKey

# specify the workspace details
ws = Workspace(
    display_name="My workspace",
    description="This example shows how to create a workspace",



While using a workspace, you have opportunities to provide feedback about Azure Machine Learning. You provide feedback by using:

  • Occasional in-product surveys
  • The smile-frown feedback tool in the banner of the workspace

You can turn off all feedback opportunities for a workspace. When off, users of the workspace won't see any surveys, and the smile-frown feedback tool is no longer visible. Use the Azure portal to turn off feedback.

  • When creating the workspace, turn off feedback from the Tags section:

    1. Select the Tags section
    2. Add the key value pair "ADMIN_HIDE_SURVEY: TRUE"
  • Turn off feedback on an existing workspace:

    1. Go to workspace resource in the Azure portal
    2. Open Tags from left navigation panel
    3. Add the key value pair "ADMIN_HIDE_SURVEY: TRUE"
    4. Select Apply.

Screenshot shows setting tags to prevent feedback in the workspace.

Download a configuration file

If you'll be running your code on a compute instance, skip this step. The compute instance creates and stores copy of this file for you.

If you plan to use code on your local environment that references this workspace, download the file:

  1. Select your workspace in Azure studio

  2. At the top right, select the workspace name, then select Download config.json

    Download config.json

Place the file into the directory structure with your Python scripts or Jupyter Notebooks. It can be in the same directory, a subdirectory named .azureml, or in a parent directory. When you create a compute instance, this file is added to the correct directory on the VM for you.

Connect to a workspace

When running machine learning tasks using the SDK, you require a MLClient object that specifies the connection to your workspace. You can create an MLClient object from parameters, or with a configuration file.

APPLIES TO: Python SDK azure-ai-ml v2 (current)

  • With a configuration file: This code reads the contents of the configuration file to find your workspace. You'll get a prompt to sign in if you aren't already authenticated.

    from import MLClient
    # read the config from the current directory
    ws_from_config = MLClient.from_config()
  • From parameters: There's no need to have a config.json file available if you use this approach.

    from import MLClient
    from import Workspace
    from azure.identity import DefaultAzureCredential
    ws = MLClient(

If you have problems in accessing your subscription, see Set up authentication for Azure Machine Learning resources and workflows, and the Authentication in Azure Machine Learning notebook.

Find a workspace

See a list of all the workspaces you can use.
You can also search for workspace inside studio. See Search for Azure Machine Learning assets (preview).

APPLIES TO: Python SDK azure-ai-ml v2 (current)

from import MLClient
from import Workspace
from azure.identity import DefaultAzureCredential

# Enter details of your subscription
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"

my_ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group)
for ws in my_ml_client.workspaces.list():
    print(, ":", ws.location, ":", ws.description)

To get details of a specific workspace:

ws = my_ml_client.workspaces.get("<AML_WORKSPACE_NAME>")
# uncomment this line after providing a workspace name above
# print(ws.location,":", ws.resource_group)

Delete a workspace

When you no longer need a workspace, delete it.


If soft-delete is enabled for the workspace, it can be recovered after deletion. If soft-delete isn't enabled, or you select the option to permanently delete the workspace, it can't be recovered. For more information, see Recover a deleted workspace.


The default behavior for Azure Machine Learning is to soft delete the workspace. This means that the workspace is not immediately deleted, but instead is marked for deletion. For more information, see Soft delete.

APPLIES TO: Python SDK azure-ai-ml v2 (current)

ml_client.workspaces.begin_delete(, delete_dependent_resources=True)

The default action isn't to delete resources associated with the workspace, that is, container registry, storage account, key vault, and application insights. Set delete_dependent_resources to True to delete these resources as well.

Clean up resources


The resources that you created can be used as prerequisites to other Azure Machine Learning tutorials and how-to articles.

If you don't plan to use any of the resources that you created, delete them so you don't incur any charges:

  1. In the Azure portal, select Resource groups on the far left.

  2. From the list, select the resource group that you created.

  3. Select Delete resource group.

    Screenshot of the selections to delete a resource group in the Azure portal.

  4. Enter the resource group name. Then select Delete.


  • Supported browsers in Azure Machine Learning studio: We recommend that you use the most up-to-date browser that's compatible with your operating system. The following browsers are supported:

    • Microsoft Edge (The new Microsoft Edge, latest version. Not Microsoft Edge legacy)
    • Safari (latest version, Mac only)
    • Chrome (latest version)
    • Firefox (latest version)
  • Azure portal:

    • If you go directly to your workspace from a share link from the SDK or the Azure portal, you can't view the standard Overview page that has subscription information in the extension. In this scenario, you also can't switch to another workspace. To view another workspace, go directly to Azure Machine Learning studio and search for the workspace name.
    • All assets (Data, Experiments, Computes, and so on) are available only in Azure Machine Learning studio. They're not available from the Azure portal.
    • Attempting to export a template for a workspace from the Azure portal may return an error similar to the following text: Could not get resource of the type <type>. Resources of this type will not be exported. As a workaround, use one of the templates provided at as the basis for your template.

Workspace diagnostics

You can run diagnostics on your workspace from Azure Machine Learning studio or the Python SDK. After diagnostics run, a list of any detected problems is returned. This list includes links to possible solutions. For more information, see How to use workspace diagnostics.

Resource provider errors

When creating an Azure Machine Learning workspace, or a resource used by the workspace, you may receive an error similar to the following messages:

  • No registered resource provider found for location {location}
  • The subscription is not registered to use namespace {resource-provider-namespace}

Most resource providers are automatically registered, but not all. If you receive this message, you need to register the provider mentioned.

The following table contains a list of the resource providers required by Azure Machine Learning:

Resource provider Why it's needed
Microsoft.MachineLearningServices Creating the Azure Machine Learning workspace.
Microsoft.Storage Azure Storage Account is used as the default storage for the workspace.
Microsoft.ContainerRegistry Azure Container Registry is used by the workspace to build Docker images.
Microsoft.KeyVault Azure Key Vault is used by the workspace to store secrets.
Microsoft.Notebooks Integrated notebooks on Azure Machine Learning compute instance.
Microsoft.ContainerService If you plan on deploying trained models to Azure Kubernetes Services.

If you plan on using a customer-managed key with Azure Machine Learning, then the following service providers must be registered:

Resource provider Why it's needed
Microsoft.DocumentDB Azure CosmosDB instance that logs metadata for the workspace.
Microsoft.Search Azure Search provides indexing capabilities for the workspace.

If you plan on using a managed virtual network with Azure Machine Learning, then the Microsoft.Network resource provider must be registered. This resource provider is used by the workspace when creating private endpoints for the managed virtual network.

For information on registering resource providers, see Resolve errors for resource provider registration.

Deleting the Azure Container Registry

The Azure Machine Learning workspace uses Azure Container Registry (ACR) for some operations. It automatically creates an ACR instance when it first needs one.


Once an Azure Container Registry has been created for a workspace, do not delete it. Doing so will break your Azure Machine Learning workspace.


Examples in this article come from workspace.ipynb.

Next steps

Once you have a workspace, learn how to Train and deploy a model.

To learn more about planning a workspace for your organization's requirements, see Organize and set up Azure Machine Learning.

For information on how to keep your Azure Machine Learning up to date with the latest security updates, see Vulnerability management.