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.

Inheritance
azureml._base_sdk_common.abstract_run_config_element._AbstractRunConfigElement
Environment

Constructor

Environment(name, **kwargs)

Parameters

name
string

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

Environment.databricks

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

docker
DockerSection

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
string

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

environment_variables
dict

A dictionary of environment variables names and values. These environment variables are set on the process where the user script is executed.

python
PythonSection

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

spark
SparkSection

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

r
RSection

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

version
string

The version of the environment.

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

add_private_pip_wheel(workspace, file_path, exist_ok=False)

Parameters

workspace
Workspace

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

file_path
str

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

exist_ok
bool
default value: False

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

Returns

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

Return type

str

build

Build a Docker image for this environment in the cloud.

build(workspace, image_build_compute=None)

Parameters

workspace
Workspace

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

image_build_compute
str
default value: None

The compute name where the image build will take place

Returns

Returns the image build details object.

Return type

build_local

Build the local Docker or conda environment.

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

Parameters

workspace
Workspace

The workspace.

platform
str
default value: None

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

kwargs
dict

Advanced keyword arguments

Returns

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

Return type

str

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

new_name
str

New environment name

Returns

New environment object

Return type

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_conda_specification(name, file_path)

Parameters

name
str

The environment name.

file_path
str

The conda environment specification YAML file path.

Returns

The environment object.

Return type

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_docker_image(name, image, container_registry=None, conda_specification=None, pip_requirements=None)

Parameters

name
str

The environment name.

image
str

fully qualified image name.

conda_specification
str
default value: None

conda specification file.

container_registry
ContainerRegistry
default value: None

private container repository details.

pip_requirements
str
default value: None

pip requirements file.

Returns

The environment object.

Return type

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.

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

Parameters

name
str

The environment name.

dockerfile
str

dockerfile content or path to the file.

conda_specification
str
default value: None

conda specification file.

pip_requirements
str
default value: None

pip requirements file.

Returns

The environment object.

Return type

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_existing_conda_environment(name, conda_environment_name)

Parameters

name
str

The environment name.

conda_environment_name
str

The name of a locally existing conda environment.

Returns

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

Return type

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.

from_pip_requirements(name, file_path, pip_version=None)

Parameters

name
str

The environment name.

file_path
str

The pip requirements file path.

pip_version
str
default value: None

Pip version for conda environment.

Returns

The environment object.

Return type

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(workspace, name, version=None, label=None)

Parameters

workspace
Workspace

The workspace that contains the environment.

name
str

The name of the environment to return.

version
str
default value: None

The version of the environment to return.

label
str
default value: None

Environment label value.

Returns

The environment object.

Return type

get_image_details

Return the Image details.

get_image_details(workspace)

Parameters

workspace
Workspace

The workspace.

Returns

Returns the image details as dict

Return type

label

Label environment object in your workspace with the specified values.

label(workspace, name, version, labels)

Parameters

workspace
Workspace

The workspace

name
str

Environment name

version
str

Environment version

labels
list[str]

Values to label Environment with

list

Return a dictionary containing environments in the workspace.

list(workspace)

Parameters

workspace
Workspace

The workspace from which to list environments.

Returns

A dictionary of environment objects.

Return type

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

load_from_directory

Load an environment definition from the files in a directory.

load_from_directory(path)

Parameters

path
str

Path to the source directory.

register

Register the environment object in your workspace.

register(workspace)

Parameters

workspace
Workspace

The workspace

name
str

Returns

Returns the environment object

Return type

save_to_directory

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

save_to_directory(path, overwrite=False)

Parameters

path
str

Path to the destination directory.

overwrite
bool
default value: False

If an existing directory should be overwritten. Defaults false.