RuntimeEnv#

class ray.runtime_env.RuntimeEnv(*, py_modules: List[str] | None = None, py_executable: str | None = None, working_dir: str | None = None, pip: List[str] | None = None, conda: Dict[str, str] | str | None = None, container: Dict[str, str] | None = None, env_vars: Dict[str, str] | None = None, worker_process_setup_hook: Callable | str | None = None, nsight: Dict[str, str] | str | None = None, rocprof_sys: str | Dict[str, Dict[str, str]] | None = None, config: Dict | RuntimeEnvConfig | None = None, _validate: bool = True, image_uri: str | None = None, uv: List[str] | None = None, preload_modules: List[str] | None = None, **kwargs)[source]#

Bases: dict

This class is used to define a runtime environment for a job, task, or actor.

See Runtime environments for detailed documentation.

This class can be used interchangeably with an unstructured dictionary in the relevant API calls.

Can specify a runtime environment whole job, whether running a script directly on the cluster, using Ray Job submission, or using Ray Client:

from ray.runtime_env import RuntimeEnv
# Starting a single-node local Ray cluster
ray.init(runtime_env=RuntimeEnv(...))
from ray.runtime_env import RuntimeEnv
# Connecting to remote cluster using Ray Client
ray.init("ray://123.456.7.89:10001", runtime_env=RuntimeEnv(...))

Can specify different runtime environments per-actor or per-task using .options() or the @ray.remote decorator:

from ray.runtime_env import RuntimeEnv
# Invoke a remote task that runs in a specified runtime environment.
f.options(runtime_env=RuntimeEnv(...)).remote()

# Instantiate an actor that runs in a specified runtime environment.
actor = SomeClass.options(runtime_env=RuntimeEnv(...)).remote()

# Specify a runtime environment in the task definition. Future invocations via
# `g.remote()` use this runtime environment unless overridden by using
# `.options()` as above.
@ray.remote(runtime_env=RuntimeEnv(...))
def g():
    pass

# Specify a runtime environment in the actor definition. Future instantiations
# via `MyClass.remote()` use this runtime environment unless overridden by
# using `.options()` as above.
@ray.remote(runtime_env=RuntimeEnv(...))
class MyClass:
    pass

Here are some examples of RuntimeEnv initialization:

# Example for using conda
RuntimeEnv(conda={
    "channels": ["defaults"], "dependencies": ["codecov"]})
RuntimeEnv(conda="pytorch_p36")   # Found on DLAMIs

# Example for using container
RuntimeEnv(
    container={"image": "anyscale/ray-ml:nightly-py38-cpu",
    "run_options": ["--cap-drop=SYS_ADMIN","--log-level=debug"]})

# Example for set env_vars
RuntimeEnv(env_vars={"OMP_NUM_THREADS": "32", "TF_WARNINGS": "none"})

# Example for set pip
RuntimeEnv(
    pip={"packages":["tensorflow", "requests"], "pip_check": False,
    "pip_version": "==22.0.2;python_version=='3.8.11'"})

# Example for using image_uri
RuntimeEnv(
    image_uri="rayproject/ray:2.39.0-py312-cu123")
Parameters:
  • py_modules (List[str] | None) – List of local paths or remote URIs (either in the GCS or external storage), each of which is an archive that Ray unpacks and inserts into the PYTHONPATH of the workers. Supported formats for remote URIs: .zip, .whl, .tar.gz, .tgz, and .tar.xz.

  • py_executable (str | None) – Path or command to the Python executable that Ray uses to launch worker processes. By default, Ray uses the same interpreter that is running the driver.

  • working_dir (str | None) – Local path or remote URI (either in the GCS or external storage) of an archive that Ray unpacks in the directory of each task/actor. Supported formats for local paths and remote URIs: .zip, .tar.gz, .tgz, and .tar.xz.

  • pip (List[str] | None) – Either a list of pip packages, a string containing the path to a pip requirements.txt file, or a Python dictionary that has three fields: 1) packages (required, List[str]): a list of pip packages, 2) pip_check (optional, bool): whether enable pip check at the end of pip install, defaults to False. 3) pip_version (optional, str): the version of pip, Ray prepends the package name “pip” in front of the pip_version to form the final requirement string, the syntax of a requirement specifier is defined in full in PEP 508.

  • conda (Dict[str, str] | str | None) – Either the conda YAML config, the name of a local conda env (e.g., “pytorch_p36”), or the path to a conda environment.yaml file. Ray automatically injects the dependency into the conda env to ensure compatibility with the cluster Ray. Ray may automatically mangle the conda name to avoid conflicts between runtime envs. This field can’t be specified at the same time as the ‘pip’ field. To use pip with conda, specify your pip dependencies within the conda YAML config: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually

  • container (Dict[str, str] | None) – Require a given Docker container image, The Ray worker process runs in a container with this image. This parameter only works alone, or with the config or env_vars parameters. The run_options list spec is here: https://docs.docker.com/engine/reference/run/ Each run_options item is passed as exactly one argument, so write a flag and its value as --flag=value or as two items. $NAME and ${NAME} in an item are expanded from the node’s whole environment, the job’s env_vars as written, and the values Ray sets for the container, such as the mounted RAY_AUTH_TOKEN_PATH; $$ is a literal $. Expanded values, like the rest of run_options, appear on podman’s command line.

  • env_vars (Dict[str, str] | None) – Environment variables to set.

  • worker_process_setup_hook (Callable | str | None) – Experimental. The setup hook that’s called after workers start and before Tasks and Actors are scheduled. A module name (string type) or callable (function) can be passed. When a module name is passed, Ray worker should be able to access the module name. When a callable is passed, callable should be serializable. When a runtime env is specified by job submission API, only a module name (string) is allowed.

  • nsight (Dict[str, str] | str | None) – Dictionary mapping nsight profile option name to it’s value.

  • rocprof_sys (str | Dict[str, Dict[str, str]] | None) – Dictionary mapping rocprof-sys profile option name and environment variables to it’s value.

  • config (Dict | RuntimeEnvConfig | None) – config for runtime environment. Either a dict or a RuntimeEnvConfig. Field: (1) setup_timeout_seconds, the timeout of runtime environment creation, timeout is in seconds.

  • _validate (bool) – Whether to validate the runtime environment when the RuntimeEnv is constructed. Disabling validation defers checks to the worker side.

  • image_uri (str | None) – URI to a container image. The Ray worker process runs in a container with this image. This parameter only works alone, or with the config or env_vars parameters.

  • uv (List[str] | None) – Either a list of pip packages, or a Python dictionary that has one field: 1) packages (required, List[str]).

  • preload_modules (List[str] | None) – (Experimental) List of Python module names to preload in the worker fork server before forking worker processes.

  • **kwargs – Additional runtime environment fields that are forwarded verbatim to the underlying runtime environment dictionary.

Methods

clear

D.clear() -> None.

conda_config

Return the conda environment spec as JSON.

conda_env_name

Return the name of the existing conda environment to use.

conda_uri

Return the URI that identifies the conda environment this runtime env creates.

copy

D.copy() -> a shallow copy of D

deserialize

Create a RuntimeEnv from a JSON string produced by serialize().

env_vars

Return the value of the env_vars field.

fromkeys

Create a new dictionary with keys from iterable and values set to value.

get

Return the value of a runtime environment field.

get_extension

Return the value of an extension field.

has_conda

Return whether the conda field is set.

has_pip

Return whether the pip field is set.

has_py_container

Return whether the container field is set.

has_uv

Return whether the uv field is set.

has_working_dir

Return whether the working_dir field is set.

image_uri

Return the value of the image_uri field.

items

D.items() -> a set-like object providing a view on D's items

java_jars

Return the entries of the java_jars field.

keys

D.keys() -> a set-like object providing a view on D's keys

nsight

Return the Nsight profiling config set through the nsight argument.

pip_config

Return the validated pip config.

pip_uri

Return the URI that identifies the pip environment this runtime env creates.

plugin_uris

Not implemented yet, always return a empty list

plugins

Return the fields that aren't built-in runtime environment fields.

pop

D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

popitem

Remove and return a (key, value) pair as a 2-tuple.

preload_modules

Return the entries of the preload_modules field.

py_container_image

Return the image of the container field.

py_container_run_options

Return the run options of the container field.

py_container_worker_path

Return the worker path of the container field.

py_executable

Return the value of the py_executable field.

py_modules

Return the entries of the py_modules field.

py_modules_uris

Return the entries of the py_modules field.

rocprof_sys

Return the rocprof-sys profiling config set through the rocprof_sys argument.

serialize

Validate this runtime environment and serialize it to JSON.

set

Set a runtime environment field, validating the value.

setdefault

Insert key with a value of default if key is not in the dictionary.

to_dict

Return the runtime environment as a plain dict.

update

D.update([E, ]**F) -> None.

uv_config

Return the validated uv config.

uv_uri

Return the URI that identifies the uv environment this runtime env creates.

values

D.values() -> an object providing a view on D's values

virtualenv_name

Return the pip field if it's a string.

working_dir

Return the value of the working_dir field.

working_dir_uri

Return the value of the working_dir field.

Attributes