Share via

az ml environment

  • Reference

Note

This reference is part of the ml extension for the Azure CLI (version 2.15.0 or higher). The extension will automatically install the first time you run an az ml environment command. Learn more about extensions.

Manage Azure ML environments.

Azure ML environments define the execution environment for jobs and endpoint deployments, encapsulating the dependencies for training and inference. These environment definitions are built into Docker images.

Commands

Name Description Type Status
az ml environment archive

Archive an environment.

 Extension GA
az ml environment create

Create an environment.

 Extension GA
az ml environment list

List environments in a workspace.

 Extension GA
az ml environment restore

Restore an archived environment.

 Extension GA
az ml environment share

Share a specific environment from workspace to registry.

 Extension GA
az ml environment show

Show details for an environment.

 Extension GA
az ml environment update

Update an environment.

 Extension GA

az ml environment archive

Archive an environment.

Archiving an environment will hide it by default from list queries (az ml environment list). You can still continue to reference and use an archived environment in your workflows. You can archive either an environment container or a specific environment version. Archiving an environment container will archive all versions of the environment under that given name. You can restore an archived environment using az ml environment restore. If the entire environment container is archived, you cannot restore individual versions of the environment - you will need to restore the environment container.

az ml environment archive --name
                          [--label]
                          [--registry-name]
                          [--resource-group]
                          [--version]
                          [--workspace-name]

Examples

Archive an environment container (archives all versions of that environment)

az ml environment archive --name my-env --resource-group my-resource-group --workspace-name my-workspace

Archive a specific environment version

az ml environment archive --name my-env --version 1 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the environment.

Optional Parameters

--label -l

Label of the environment.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the environment.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment create

Create an environment.

Environments can be defined from a Docker image, Dockerfile, or Conda file. Azure ML maintains a set of CPU and GPU Docker images that you can use as base images. For information on these images, see https://github.com/Azure/AzureML-Containers.

The created environment will be tracked in the workspace under the specified name and version.

az ml environment create [--build-context]
                         [--conda-file]
                         [--datastore]
                         [--description]
                         [--dockerfile-path]
                         [--file]
                         [--image]
                         [--name]
                         [--no-wait]
                         [--os-type]
                         [--registry-name]
                         [--resource-group]
                         [--set]
                         [--tags]
                         [--version]
                         [--workspace-name]

Examples

Create an environment from a YAML specification file

az ml environment create --file my_env.yml --resource-group my-resource-group --workspace-name my-workspace

Create an environment from a docker image

az ml environment create --name my-env --version 1 --file my_env.yml  --image pytorch/pytorch --resource-group my-resource-group --workspace-name my-workspace

Create an environment from a build context

az ml environment create --name my-env --version 1 --file my_env.yml  --build-context envs/context/ --dockerfile-path Dockerfile --resource-group my-resource-group --workspace-name my-workspace

Create an environment from a conda specification

az ml environment create --name my-env --version 1 --file my_env.yml  --conda-file conda_dep.yml --image mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04 --resource-group my-resource-group --workspace-name my-workspace

Create an environment in registry from a YAML specification file

az ml environment create --file my_env.yml --registry-name my-registry-name --resource-group my-resource-group

Optional Parameters

--build-context -b

Local path to the directory to use as a Docker build context. --build-context/-b and --image/-i are mutually exclusive arguments.

--conda-file -c

Local path to a conda specification file. --image/-i must also be specified if this argument is used.

--datastore

The datastore to upload the local artifact to.

--description

Description of the environment.

--dockerfile-path -d

Relative path to the Dockerfile within the directory specified by --build-context/-b. If omitted, './Dockerfile' is used.

Default value: /Dockerfile
--file -f

Local path to the YAML file containing the Azure ML environment specification. The YAML reference docs for environment can be found at: https://aka.ms/ml-cli-v2-environment-yaml-reference.

--image -i

Docker image. --image/-i and --build-context/-b are mutually exclusive arguments.

--name -n

Name of the environment.

--no-wait

Do not wait for the long-running operation to finish.

Default value: False
--os-type

Type of operating system. Allowed values: linux, windows. Default: linux.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--tags

Space-separated key-value pairs for the tags of the object.

--version -v

Version of the environment.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment list

List environments in a workspace.

az ml environment list [--archived-only]
                       [--include-archived]
                       [--max-results]
                       [--name]
                       [--registry-name]
                       [--resource-group]
                       [--workspace-name]

Examples

List all the environments in a workspace

az ml environment list --resource-group my-resource-group --workspace-name my-workspace

List all the environment versions for the specified name in a workspace

az ml environment list --name my-env --resource-group my-resource-group --workspace-name my-workspace

List all the environments in a workspace using --query argument to execute a JMESPath query on the results of commands.

az ml environment list --query "[].{Name:name}"  --output table --resource-group my-resource-group --workspace-name my-workspace

List all the environments in a registry

az ml environment list --registry-name my-registry-name --resource-group my-resource-group

List all the environment versions for the specified name in a registry

az ml environment list --name my-env --registry-name my-registry-name --resource-group my-resource-group

Optional Parameters

--archived-only

List archived environments only.

Default value: False
--include-archived

List archived environments and active environments.

Default value: False
--max-results -r

Max number of results to return.

--name -n

Name of the environment. If provided, all the environment versions under this name will be returned.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment restore

Restore an archived environment.

When an archived environment is restored, it will no longer be hidden from list queries (az ml environment list). If an entire environment container is archived, you can restore that archived container. This will restore all versions of the environment under that given name. You cannot restore only a specific environment version if the entire environment container is archived - you will need to restore the entire container. If only an individual environment version was archived, you can restore that specific version.

az ml environment restore --name
                          [--label]
                          [--registry-name]
                          [--resource-group]
                          [--version]
                          [--workspace-name]

Examples

Restore an archived environment container (restores all versions of that environment)

az ml environment restore --name my-env --resource-group my-resource-group --workspace-name my-workspace

Restore a specific archived environment version

az ml environment restore --name my-env --version 1 --resource-group my-resource-group --workspace-name my-workspace

Required Parameters

--name -n

Name of the environment.

Optional Parameters

--label -l

Label of the environment.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the environment.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment share

Share a specific environment from workspace to registry.

Copy an existing environment from a workspace to a registry for cross-workspace reuse.

az ml environment share --name
                        --registry-name
                        --share-with-name
                        --share-with-version
                        --version
                        [--resource-group]
                        [--workspace-name]

Examples

Share an existing environment from workspace to registry

az ml environment share --name my-environment --version my-version --resource-group my-resource-group --workspace-name my-workspace --share-with-name new-name-in-registry --share-with-version new-version-in-registry --registry-name my-registry

Required Parameters

--name -n

Name of the environment.

--registry-name

Destination registry.

--share-with-name

Name of the environment to be created with.

--share-with-version

Version of the environment to be created with.

--version -v

Version of the environment.

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment show

Show details for an environment.

az ml environment show --name
                       [--label]
                       [--registry-name]
                       [--resource-group]
                       [--version]
                       [--workspace-name]

Examples

Show details for an environment with the specified name and version

az ml environment show --name my-env --version 1 --resource-group my-resource-group --workspace-name my-workspace

Show details for an environment in registry with the specified name and version

az ml environment show --name my-env --version 1 --registry-name my-registry-name --resource-group my-resource-group

Required Parameters

--name -n

Name of the environment.

Optional Parameters

--label -l

Label of the environment.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--version -v

Version of the environment.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml environment update

Update an environment.

Only the 'description' and 'tags' properties can be updated.

az ml environment update --name
                         [--add]
                         [--force-string]
                         [--label]
                         [--registry-name]
                         [--remove]
                         [--resource-group]
                         [--set]
                         [--version]
                         [--workspace-name]

Required Parameters

--name -n

Name of the environment.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

Default value: []
--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

Default value: False
--label -l

Label of the environment.

--registry-name

If provided, the command will target the registry instead of a workspace. Hence resource group and workspace won't be required.

--remove

Remove a property or an element from a list. Example: --remove property.list <indexToRemove> OR --remove propertyToRemove.

Default value: []
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

Default value: []
--version -v

Version of the environment.

--workspace-name -w

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.