ray.runtime_env.RuntimeEnv#

class ray.runtime_env.RuntimeEnv(*, py_modules: List[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, config: Dict | RuntimeEnvConfig | None = None, _validate: bool = True, mpi: Dict | None = None, image_uri: str | None = None, uv: 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 of URIs (either in the GCS or external storage), each of which is a zip file that Ray unpacks and inserts into the PYTHONPATH of the workers.

  • working_dir – URI (either in the GCS or external storage) of a zip file that Ray unpacks in the directory of each task/actor.

  • pip – 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.

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

  • conda – 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 – 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/

  • env_vars – Environment variables to set.

  • worker_process_setup_hook – (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 – Dictionary mapping nsight profile option name to it’s value.

  • config – 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.

  • image_uri – 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.

Methods

clear

copy

fromkeys

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

items

keys

plugin_uris

Not implemented yet, always return a empty list

pop

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem

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

setdefault

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

update

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values

Attributes

extensions_fields

known_fields