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

[!INCLUDE sdk v2]

[!div class="op_single_selector" title1="Select the version of Azure Machine Learning SDK you are using:"]

v1

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.

Prerequisites

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. Provide your subscription details

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

Get a handle to the subscription. ml_client will be used in all the Python code in this article.

# get a handle to the subscription

from azure.ai.ml 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 Azure Active Directory you wish to use into the `DefaultAzureCredential`. Find your tenant ID from the [Azure portal](https://portal.azure.com) under **Azure Active Directory, External Identities**.
            
        ```python
        DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
        ```
            
    * (Optional) If you're working on a [sovereign cloud](reference-machine-learning-cloud-parity.md)**, specify the sovereign cloud to authenticate with into the `DefaultAzureCredential`..
            
        ```python
        from azure.identity import AzureAuthorityHosts
        DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT))
        ```

Limitations

[!INCLUDE register-namespace]

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.

[!INCLUDE application-insight]

Create a workspace

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

Python SDK

[!INCLUDE sdk v2]

Default specification. By default, dependent resources and the resource group will be 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 azure.ai.ml.entities import Workspace
import datetime

basic_workspace_name = "mlw-basic-prod-" + datetime.datetime.now().strftime(
    "%Y%m%d%H%M"
)

ws_basic = Workspace(
    name=basic_workspace_name,
    location="eastus",
    display_name="Basic workspace-example",
    description="This example shows how to create a basic workspace",
    hbi_workspace=False,
    tags=dict(purpose="demo"),
)

ws_basic = ml_client.workspaces.begin_create(ws_basic).result()
print(ws_basic)

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 azure.ai.ml.entities import Workspace

basic_ex_workspace_name = "mlw-basicex-prod-" + datetime.datetime.now().strftime(
    "%Y%m%d%H%M"
)

# 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>"
    ws_basic.storage_account
)
existing_container_registry = (
    # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<CONTAINER_REGISTRY>"
    ws_basic.container_registry
)
existing_key_vault = (
    # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>"
    ws_basic.key_vault
)
existing_application_insights = (
    # e.g. "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.insights/components/<APP_INSIGHTS>"
    ws_basic.application_insights
)

ws_with_existing_resources = Workspace(
    name=basic_ex_workspace_name,
    location="eastus",
    display_name="Bring your own dependent resources-example",
    description="This sample specifies a workspace configuration with existing dependent resources",
    storage_account=existing_storage_account,
    container_registry=existing_container_registry,
    key_vault=existing_key_vault,
    application_insights=existing_application_insights,
    tags=dict(purpose="demonstration"),
)

ws_with_existing_resources = ml_client.begin_create_or_update(
    ws_with_existing_resources
).result()

print(ws_with_existing_resources)

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.

Portal

Sign in to the Azure portal by using the credentials for your Azure subscription.
In the upper-left corner of Azure portal, select + Create a resource.

:::image type="content" source="media/how-to-manage-workspace/create-workspace.gif" alt-text="Screenshot show how to create a workspace in Azure portal.":::
Use the search bar to find Machine Learning.
Select Machine Learning.
In the Machine Learning pane, select Create to begin.

Provide the following information to configure your new workspace:

Field	Description
Workspace name	Enter a unique name that identifies your workspace. In this example, we use docs-ws. Names must be unique across the resource group. Use a name that's easy to recall and to differentiate from workspaces created by others. The workspace name is case-insensitive.
Subscription	Select the Azure subscription that you want to use.
Resource group	Use an existing resource group in your subscription or enter a name to create a new resource group. A resource group holds related resources for an Azure solution. In this example, we use docs-aml. You need contributor or owner role to use an existing resource group. For more information about access, see Manage access to an Azure Machine Learning workspace.
Region	Select the Azure region closest to your users and the data resources to create your workspace.
Storage account	The default storage account for the workspace. By default, a new one is created.
Key Vault	The Azure Key Vault used by the workspace. By default, a new one is created.
Application Insights	The application insights instance for the workspace. By default, a new one is created.
Container Registry	The Azure Container Registry for the workspace. By default, a new one isn't_ initially created for the workspace. Instead, it's created once you need it when creating a Docker image during training or deployment.

:::image type="content" source="media/how-to-manage-workspace/create-workspace-form.png" alt-text="Configure your workspace.":::

When you're finished configuring the workspace, select Review + Create. Optionally, use the Networking and Advanced sections to configure more settings for the workspace.
Review the settings and make any other changes or corrections. When you're satisfied with the settings, select Create.

[!Warning] It can take several minutes to create your workspace in the cloud.

When the process is finished, a deployment success message appears.
To view the new workspace, select Go to resource.

Networking

Important

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

Python SDK

[!INCLUDE sdk v2]

# Creating a unique workspace name with current datetime to avoid conflicts
import datetime
from azure.ai.ml.entities import Workspace

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

ws_private = Workspace(
    name=basic_private_link_workspace_name,
    location="eastus",
    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.",
    image_build_compute="cpu-compute",
    public_network_access="Disabled",
    tags=dict(purpose="demonstration"),
)

ml_client.workspaces.begin_create(ws_private).result()

This class requires an existing virtual network.

Portal

The default network configuration is to use a Public endpoint, which is accessible on the public internet. To limit access to your workspace to an Azure Virtual Network you've created, you can instead select Private endpoint as the Connectivity method, and then use + Add to configure the endpoint.

:::image type="content" source="media/how-to-manage-workspace/select-private-endpoint.png" alt-text="Private endpoint selection":::
On the Create private endpoint form, set the location, name, and virtual network to use. If you'd like to use the endpoint with a Private DNS Zone, select Integrate with private DNS zone and select the zone using the Private DNS Zone field. Select OK to create the endpoint.

:::image type="content" source="media/how-to-manage-workspace/create-private-endpoint.png" alt-text="Private endpoint creation":::
When you're finished configuring networking, you can select Review + Create, or advance to the optional Advanced configuration.

Advanced

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.

Important

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:

Important

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

Python SDK

[!INCLUDE sdk v2]

from azure.ai.ml.entities import Workspace, CustomerManagedKey

# specify the workspace details
ws = Workspace(
    name="my_workspace",
    location="eastus",
    display_name="My workspace",
    description="This example shows how to create a workspace",
    customer_managed_key=CustomerManagedKey(
        key_vault="/subscriptions/<SUBSCRIPTION_ID>/resourcegroups/<RESOURCE_GROUP>/providers/microsoft.keyvault/vaults/<VAULT_NAME>"
        key_uri="<KEY-IDENTIFIER>"
    )
    tags=dict(purpose="demo")
)

ml_client.workspaces.begin_create(ws)

Portal

Select Customer-managed keys, and then select Click to select key.

:::image type="content" source="media/how-to-manage-workspace/advanced-workspace.png" alt-text="Customer-managed keys":::
On the Select key from Azure Key Vault form, select an existing Azure Key Vault, a key that it contains, and the version of the key. This key is used to encrypt the data stored in Azure Cosmos DB. Finally, use the Select button to use this key.

:::image type="content" source="media/how-to-manage-workspace/select-key-vault.png" alt-text="Select the key":::

Download a configuration file

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

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

Select your workspace in Azure studio
At the top right, select the workspace name, then select 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.

[!INCLUDE sdk v2]

With a configuration file: This code will read 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 azure.ai.ml 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 azure.ai.ml import MLClient
from azure.ai.ml.entities import Workspace
from azure.identity import DefaultAzureCredential

ws = MLClient(
    DefaultAzureCredential(),
    subscription_id="<SUBSCRIPTION_ID>",
    resource_group_name="<RESOURCE_GROUP>",
    workspace_name="<AML_WORKSPACE_NAME>",
)
print(ws)

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

Python SDK

[!INCLUDE sdk v2]

from azure.ai.ml import MLClient
from azure.ai.ml.entities 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.name, ":", 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)

Portal

Sign in to the Azure portal.
In the top search field, type Machine Learning.
Select Machine Learning.
Look through the list of workspaces found. You can filter based on subscription, resource groups, and locations.
Select a workspace to display its properties.

Delete a workspace

When you no longer need a workspace, delete it.

[!INCLUDE machine-learning-delete-workspace]

If you accidentally deleted your workspace, you may still be able to retrieve your notebooks. For details, see Failover for business continuity and disaster recovery.

Python SDK

[!INCLUDE sdk v2]

ml_client.workspaces.begin_delete(name=ws_basic.name, 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.

Portal

In the Azure portal, select Delete at the top of the workspace you wish to delete.

:::image type="content" source="./media/how-to-manage-workspace/delete-workspace.png" alt-text="Delete workspace":::

Clean up resources

[!INCLUDE aml-delete-resource-group]

Troubleshooting

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 https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.machinelearningservices as the basis for your template.

Workspace diagnostics

[!INCLUDE machine-learning-workspace-diagnostics]

Resource provider errors

[!INCLUDE machine-learning-resource-provider]

Deleting the Azure Container Registry

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

[!INCLUDE machine-learning-delete-acr]

Examples

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.

If you need to move a workspace to another Azure subscription, see How to move a workspace.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

how-to-manage-workspace.md

how-to-manage-workspace.md

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

Prerequisites

Limitations

Create a workspace

Python SDK

Portal

Networking

Python SDK

Portal

Advanced

Use your own data encryption key

Python SDK

Portal

Download a configuration file

Connect to a workspace

Find a workspace

Python SDK

Portal

Delete a workspace

Python SDK

Portal

Clean up resources

Troubleshooting

Workspace diagnostics

Resource provider errors

Deleting the Azure Container Registry

Examples

Next steps

Files

how-to-manage-workspace.md

Latest commit

History

how-to-manage-workspace.md

File metadata and controls

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

Prerequisites

Limitations

Create a workspace

Networking

Advanced

Use your own data encryption key

Download a configuration file

Connect to a workspace

Find a workspace

Delete a workspace

Clean up resources

Troubleshooting

Workspace diagnostics

Resource provider errors

Deleting the Azure Container Registry

Examples

Next steps