Environment Class

Reference

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

Initialize a new Environment object.
Use one of the Environment class methods: from_conda_specification, from_pip_requirements, or from_existing_conda_environment.
Use the submit method of the Experiment class to submit an experiment run without specifying an environment, including with an Estimator object.

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	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".
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.
asset_id	string 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	Workspace 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	bool 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	Workspace 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
ImageBuildDetails	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	Workspace The workspace.
platform	str Platform. One of Linux, Windows or OSX. Current platform will be used by default. default value: None
kwargs Required	dict 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
Environment	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
Environment	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	DockerBuildContext The DockerBuildContext object.

Returns

Type	Description
Environment	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	ContainerRegistry private container repository details. default value: None
pip_requirements	str pip requirements file. default value: None

Returns

Type	Description
Environment	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
Environment	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
Environment	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
Environment	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	Workspace 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
Environment	The environment object.

get_image_details

Return the Image details.

get_image_details(workspace)

Parameters

Name	Description
workspace Required	Workspace The workspace.

Returns

Type	Description
DockerImageDetails	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	Workspace The workspace
name Required	str Environment name
version Required	str Environment version
labels Required	list[str] Values to label Environment with

list

Return a dictionary containing environments in the workspace.

static list(workspace)

Parameters

Name	Description
workspace Required	Workspace 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(workspace)

Parameters

Name	Description
workspace Required	Workspace The workspace
name Required	str

Returns

Type	Description
Environment	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	bool If an existing directory should be overwritten. Defaults false. default value: False

Attributes

environment_variables

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

Environment Class

Constructor

Parameters

Remarks

Variables

Methods

add_private_pip_wheel

Parameters

Returns

build

Parameters

Returns

build_local

Parameters

Returns

Remarks

clone

Parameters

Returns

from_conda_specification

Parameters

Returns

from_docker_build_context

Parameters

Returns

from_docker_image

Parameters

Returns

Remarks

from_dockerfile

Parameters

Returns

from_existing_conda_environment

Parameters

Returns

from_pip_requirements

Parameters

Returns

get

Parameters

Returns

get_image_details

Parameters

Returns

label

Parameters

list

Parameters

Returns

load_from_directory

Parameters

register

Parameters

Returns

save_to_directory

Parameters

Attributes

environment_variables

Feedback

Feedback

Additional resources