Environment class

Definition

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.

Environment(name, **kwargs)
Inheritance
builtins.object
azureml._base_sdk_common.abstract_run_config_element._AbstractRunConfigElement
Environment

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
class
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(workspace, file_path, exist_ok=False)

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(workspace, image_build_compute=None)

Build a Docker image for this environment in the cloud.

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

Build the local Docker or conda environment.

clone(new_name)

Clone the environment object.

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

from_conda_specification(name, file_path)

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

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

Create an environment object created from a pip requirements file.

get(workspace, name, version=None)

Return the environment object.

get_image_details(workspace)

Return the Image details.

list(workspace)

Return a dictionary containing environments in the workspace.

load_from_directory(path)

Load an environment definition from the files in a directory.

register(workspace)

Register the environment object in your workspace.

save_to_directory(path, overwrite=False)

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

add_private_pip_wheel(workspace, file_path, exist_ok=False)

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(workspace, image_build_compute=None)

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(workspace, platform=None, **kwargs)

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(new_name)

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

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

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

Create an environment object created from a pip requirements file.

from_pip_requirements(name, file_path)

Parameters

name
str

The environment name.

file_path
str

The pip requirements file path.

Returns

The environment object.

Return type

get(workspace, name, version=None)

Return the environment object.

get(workspace, name, version=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.

Returns

The environment object.

Return type

get_image_details(workspace)

Return the Image details.

get_image_details(workspace)

Parameters

workspace
Workspace

The workspace.

Returns

Returns the image details as dict

Return type

list(workspace)

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

builtin.dict[str, Environment]

load_from_directory(path)

Load an environment definition from the files in a directory.

load_from_directory(path)

Parameters

path
str

Path to the source directory.

register(workspace)

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(path, overwrite=False)

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.