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:
dictThis 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.remotedecorator: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 thepip_versionto 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
configorenv_varsparameters. Therun_optionslist spec is here: https://docs.docker.com/engine/reference/run/ Eachrun_optionsitem is passed as exactly one argument, so write a flag and its value as--flag=valueor as two items.$NAMEand${NAME}in an item are expanded from the node’s whole environment, the job’senv_varsas written, and the values Ray sets for the container, such as the mountedRAY_AUTH_TOKEN_PATH;$$is a literal$. Expanded values, like the rest ofrun_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
RuntimeEnvis 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
configorenv_varsparameters.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
D.clear() -> None.
Return the conda environment spec as JSON.
Return the name of the existing conda environment to use.
Return the URI that identifies the conda environment this runtime env creates.
D.copy() -> a shallow copy of D
Create a RuntimeEnv from a JSON string produced by
serialize().Return the value of the
env_varsfield.Create a new dictionary with keys from iterable and values set to value.
Return the value of a runtime environment field.
Return the value of an extension field.
Return whether the
condafield is set.Return whether the
pipfield is set.Return whether the
containerfield is set.Return whether the
uvfield is set.Return whether the
working_dirfield is set.Return the value of the
image_urifield.D.items() -> a set-like object providing a view on D's items
Return the entries of the
java_jarsfield.D.keys() -> a set-like object providing a view on D's keys
Return the Nsight profiling config set through the
nsightargument.Return the validated
pipconfig.Return the URI that identifies the pip environment this runtime env creates.
Not implemented yet, always return a empty list
Return the fields that aren't built-in runtime environment fields.
D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
Remove and return a (key, value) pair as a 2-tuple.
Return the entries of the
preload_modulesfield.Return the image of the
containerfield.Return the run options of the
containerfield.Return the worker path of the
containerfield.Return the value of the
py_executablefield.Return the entries of the
py_modulesfield.Return the entries of the
py_modulesfield.Return the rocprof-sys profiling config set through the
rocprof_sysargument.Validate this runtime environment and serialize it to JSON.
Set a runtime environment field, validating the value.
Insert key with a value of default if key is not in the dictionary.
Return the runtime environment as a plain dict.
D.update([E, ]**F) -> None.
Return the validated
uvconfig.Return the URI that identifies the uv environment this runtime env creates.
D.values() -> an object providing a view on D's values
Return the
pipfield if it's a string.Return the value of the
working_dirfield.Return the value of the
working_dirfield.Attributes