az ml environment

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

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

az ml environment archive	Archive an environment.
az ml environment create	Create an environment.
az ml environment list	List environments in a workspace.
az ml environment restore	Restore an archived environment.
az ml environment show	Show details for an environment.
az ml environment update	Update an environment.

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
                          --resource-group
                          --workspace-name
                          [--label]
                          [--version]

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.

--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 group using az configure --defaults workspace=<name>.

Optional Parameters

--label -l

Label of the environment.

--version -v

Version of the environment.

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.

--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 --resource-group
                         --workspace-name
                         [--build-context]
                         [--conda-file]
                         [--description]
                         [--dockerfile-path]
                         [--file]
                         [--image]
                         [--name]
                         [--os-type]
                         [--registry-name]
                         [--set]
                         [--tags]
                         [--version]

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

Required 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 group using az configure --defaults workspace=<name>.

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.

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

--os-type

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

--registry-name

This will interact with the registry provided name, not use workspace.

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

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.

--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 --resource-group
                       --workspace-name
                       [--archived-only]
                       [--include-archived]
                       [--max-results]
                       [--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

Required 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 group using az configure --defaults workspace=<name>.

Optional Parameters

--archived-only

List archived environments only.

--include-archived

List archived environments and active environments.

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

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.

--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
                          --resource-group
                          --workspace-name
                          [--label]
                          [--version]

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.

--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 group using az configure --defaults workspace=<name>.

Optional Parameters

--label -l

Label of the environment.

--version -v

Version of the environment.

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.

--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
                       --resource-group
                       --workspace-name
                       [--label]
                       [--version]

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

Required Parameters

--name -n

Name of the environment.

--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 group using az configure --defaults workspace=<name>.

Optional Parameters

--label -l

Label of the environment.

--version -v

Version of the environment.

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.

--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
                         --resource-group
                         --workspace-name
                         [--add]
                         [--force-string]
                         [--label]
                         [--registry-name]
                         [--remove]
                         [--set]
                         [--version]

Required Parameters

--name -n

Name of the environment.

--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 group using az configure --defaults workspace=<name>.

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

--force-string

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

--label -l

Label of the environment.

--registry-name

This will interact with the registry provided name, not use workspace.

--remove

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

--set

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

--version -v

Version of the environment.

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.

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