Environment Class

Configures a reproducible Python environment for machine learning experiments.

An Environment defines Python packages, environment variables, and Docker settings that are used in machine learning experiments, including in data preparation, training, and deployment to a web service. An Environment is managed and versioned in an Azure Machine Learning Workspace. You can update an existing environment and retrieve a version to reuse. Environments are exclusive to the workspace they are created in and can't be used across different workspaces.

For more information about environments, see Create and manage reusable environments.

Class Environment constructor.

Inheritance
azureml._base_sdk_common.abstract_run_config_element._AbstractRunConfigElement
Environment

Constructor

Environment(name, **kwargs)

Parameters

Name Description
name
Required

The name of the environment.

Note

Do not start your environment name with "Microsoft" or "AzureML". The prefixes "Microsoft" and "AzureML" are reserved for curated environments. For more information about curated environments, see Create and manage reusable environments.

Remarks

Azure Machine Learning provides curated environments, which are predefined environments that offer good starting points for building your own environments. Curated environments are backed by cached Docker images, providing a reduced run preparation cost. For more information about curated environments, see Create and manage reusable environments.

There are a number of ways environment are created in the Azure Machine Learning, including when you:

The following example shows how to instantiate a new environment.


   from azureml.core import Environment
   myenv = Environment(name="myenv")

You can manage an environment by registering it. Doing so allows you to track the environment's versions, and reuse them in future runs.


   myenv.register(workspace=ws)

For more samples of working with environments, see the Jupyter Notebook Using environments.

Variables

Name Description
Environment.databricks

The section configures azureml.core.databricks.DatabricksSection library dependencies.

docker

This section configures settings related to the final Docker image built to the specifications of the environment and whether to use Docker containers to build the environment.

inferencing_stack_version

This section specifies the inferencing stack version added to the image. To avoid adding an inferencing stack, do not set this value. Valid value: "latest".

python

This section specifies which Python environment and interpreter to use on the target compute.

spark

The section configures Spark settings. It is only used when framework is set to PySpark.

r

This section specifies which R environment to use on the target compute.

version

The version of the environment.

asset_id

Asset ID. Populates when an environment is registered.

Methods

add_private_pip_wheel

Upload the private pip wheel file on disk to the Azure storage blob attached to the workspace.

Throws an exception if a private pip wheel with the same name already exists in the workspace storage blob.

build

Build a Docker image for this environment in the cloud.

build_local

Build the local Docker or conda environment.

clone

Clone the environment object.

Returns a new instance of environment object with a new name.

from_conda_specification

Create environment object from an environment specification YAML file.

To get an environment specification YAML file, see Managing environments in the conda user guide.

from_docker_build_context

Create environment object from a Docker build context.

from_docker_image

Create environment object from a base docker image with optional python dependenies.

Python layer will be added to the environment if conda_specification or pip_requirements is specified. conda_specification and pip_requirements are mutually exclusive.

from_dockerfile

Create environment object from a Dockerfile with optional python dependenies.

Python layer will be added to the environment if conda_specification or pip_requirements is specified. conda_specification and pip_requirements are mutually exclusive.

from_existing_conda_environment

Create an environment object created from a locally existing conda environment.

To get a list of existing conda environments, run conda env list. For more information, see Managing environments in the conda user guide.

from_pip_requirements

Create an environment object created from a pip requirements file.

Unpinned pip dependency will be added if pip_version is not specified.

get

Return the environment object.

If label is specified, the object previously labeled with the value will be returned. Only one of version or label parameters can be specified. If both are missed, the latest version of the Environment object will be returned.

get_image_details

Return the Image details.

label

Label environment object in your workspace with the specified values.

list

Return a dictionary containing environments in the workspace.

load_from_directory

Load an environment definition from the files in a directory.

register

Register the environment object in your workspace.

save_to_directory

Save an environment definition to a directory in an easily editable format.

add_private_pip_wheel

Upload the private pip wheel file on disk to the Azure storage blob attached to the workspace.

Throws an exception if a private pip wheel with the same name already exists in the workspace storage blob.

static add_private_pip_wheel(workspace, file_path, exist_ok=False)

Parameters

Name Description
workspace
Required

The workspace object to use to register the private pip wheel.

file_path
Required
str

Path to the local pip wheel on disk, including the file extension.

exist_ok

Indicates whether to throw an exception if the wheel already exists.

Default value: False

Returns

Type Description
str

Returns the full URI to the uploaded pip wheel on Azure blob storage to use in conda dependencies.

build

Build a Docker image for this environment in the cloud.

build(workspace, image_build_compute=None)

Parameters

Name Description
workspace
Required

The workspace and its associated Azure Container Registry where the image is stored.

image_build_compute
str

The compute name where the image build will take place

Default value: None

Returns

Type Description

Returns the image build details object.

build_local

Build the local Docker or conda environment.

build_local(workspace, platform=None, **kwargs)

Parameters

Name Description
workspace
Required

The workspace.

platform
str

Platform. One of Linux, Windows or OSX. Current platform will be used by default.

Default value: None
kwargs
Required

Advanced keyword arguments

Returns

Type Description
str

Streams the on-going Docker or conda built output to the console.

Remarks

The following examples show how to build a local environment. Please make sure workspace is instantiated as a valid azureml.core.workspace.Workspace object

Build local conda environment


   from azureml.core import Environment
   myenv = Environment(name="myenv")
   registered_env = myenv.register(workspace)
   registered_env.build_local(workspace)

Build local docker environment


   from azureml.core import Environment
   myenv = Environment(name="myenv")
   registered_env = myenv.register(workspace)
   registered_env.build_local(workspace, useDocker=True)

Build docker image locally and optionally push it to the container registry associated with the workspace


   from azureml.core import Environment
   myenv = Environment(name="myenv")
   registered_env = myenv.register(workspace)
   registered_env.build_local(workspace, useDocker=True, pushImageToWorkspaceAcr=True)

clone

Clone the environment object.

Returns a new instance of environment object with a new name.

clone(new_name)

Parameters

Name Description
new_name
Required
str

New environment name

Returns

Type Description

New environment object

from_conda_specification

Create environment object from an environment specification YAML file.

To get an environment specification YAML file, see Managing environments in the conda user guide.

static from_conda_specification(name, file_path)

Parameters

Name Description
name
Required
str

The environment name.

file_path
Required
str

The conda environment specification YAML file path.

Returns

Type Description

The environment object.

from_docker_build_context

Create environment object from a Docker build context.

static from_docker_build_context(name, docker_build_context)

Parameters

Name Description
name
Required
str

The environment name.

docker_build_context
Required

The DockerBuildContext object.

Returns

Type Description

The environment object.

from_docker_image

Create environment object from a base docker image with optional python dependenies.

Python layer will be added to the environment if conda_specification or pip_requirements is specified. conda_specification and pip_requirements are mutually exclusive.

static from_docker_image(name, image, container_registry=None, conda_specification=None, pip_requirements=None)

Parameters

Name Description
name
Required
str

The environment name.

image
Required
str

fully qualified image name.

conda_specification
str

conda specification file.

Default value: None
container_registry

private container repository details.

Default value: None
pip_requirements
str

pip requirements file.

Default value: None

Returns

Type Description

The environment object.

Remarks

If base image is from private repository that requires authorization, and authorization is not set on the AzureML workspace level, container_registry is required

from_dockerfile

Create environment object from a Dockerfile with optional python dependenies.

Python layer will be added to the environment if conda_specification or pip_requirements is specified. conda_specification and pip_requirements are mutually exclusive.

static from_dockerfile(name, dockerfile, conda_specification=None, pip_requirements=None)

Parameters

Name Description
name
Required
str

The environment name.

dockerfile
Required
str

Dockerfile content or path to the file.

conda_specification
str

conda specification file.

Default value: None
pip_requirements
str

pip requirements file.

Default value: None

Returns

Type Description

The environment object.

from_existing_conda_environment

Create an environment object created from a locally existing conda environment.

To get a list of existing conda environments, run conda env list. For more information, see Managing environments in the conda user guide.

static from_existing_conda_environment(name, conda_environment_name)

Parameters

Name Description
name
Required
str

The environment name.

conda_environment_name
Required
str

The name of a locally existing conda environment.

Returns

Type Description

The environment object or None if exporting the conda specification file fails.

from_pip_requirements

Create an environment object created from a pip requirements file.

Unpinned pip dependency will be added if pip_version is not specified.

static from_pip_requirements(name, file_path, pip_version=None)

Parameters

Name Description
name
Required
str

The environment name.

file_path
Required
str

The pip requirements file path.

pip_version
str

Pip version for conda environment.

Default value: None

Returns

Type Description

The environment object.

get

Return the environment object.

If label is specified, the object previously labeled with the value will be returned. Only one of version or label parameters can be specified. If both are missed, the latest version of the Environment object will be returned.

static get(workspace, name, version=None, label=None)

Parameters

Name Description
workspace
Required

The workspace that contains the environment.

name
Required
str

The name of the environment to return.

version
str

The version of the environment to return.

Default value: None
label
str

Environment label value.

Default value: None

Returns

Type Description

The environment object.

get_image_details

Return the Image details.

get_image_details(workspace)

Parameters

Name Description
workspace
Required

The workspace.

Returns

Type Description

Returns the image details as dict

label

Label environment object in your workspace with the specified values.

static label(workspace, name, version, labels)

Parameters

Name Description
workspace
Required

The workspace

name
Required
str

Environment name

version
Required
str

Environment version

labels
Required

Values to label Environment with

list

Return a dictionary containing environments in the workspace.

static list(workspace)

Parameters

Name Description
workspace
Required

The workspace from which to list environments.

Returns

Type Description
<xref:builtin.dict>[str, Environment]

A dictionary of environment objects.

load_from_directory

Load an environment definition from the files in a directory.

static load_from_directory(path)

Parameters

Name Description
path
Required
str

Path to the source directory.

register

Register the environment object in your workspace.

register(workspace)

Parameters

Name Description
workspace
Required

The workspace

name
Required
str

Returns

Type Description

Returns the environment object

save_to_directory

Save an environment definition to a directory in an easily editable format.

save_to_directory(path, overwrite=False)

Parameters

Name Description
path
Required
str

Path to the destination directory.

overwrite

If an existing directory should be overwritten. Defaults false.

Default value: False

Attributes

environment_variables

Use azureml.core.RunConfiguration object to set runtime variables.