Handling Dependencies

Use runtime environments to specify per-task, per-actor, and per-job Python and system dependencies.

A runtime environment is a description of dependencies — Python packages, working directory, environment variables, container image — that Ray installs into a worker before running a task or actor.

Define a runtime environment

Pass a dict to ray.init, the runtime_env decorator argument, or .options(runtime_env=...).

runtime_env = {
    "pip": ["torch==2.1.0", "transformers==4.38.0"],
    "env_vars": {"CUDA_VISIBLE_DEVICES": "0"},
    "working_dir": "./my_project",
}

ray.init(runtime_env=runtime_env)

Per-task and per-actor environments

Different tasks can need different dependencies. Specify per call:

@ray.remote(runtime_env={"pip": ["scikit-learn==1.4.0"]})
def train_sklearn(data):
    from sklearn.ensemble import RandomForestClassifier
    ...

Or override at submission time:

train_sklearn.options(runtime_env={"pip": ["scikit-learn==1.5.0"]}).remote(data)

Supported fields

Field	What it does
pip	List of pip requirements, or a path to a requirements.txt.
conda	Conda env YAML or named env.
uv	Use uv for faster pip installs.
working_dir	Local directory or remote URI; uploaded to workers.
py_modules	List of local modules to ship to workers.
env_vars	Environment variables to set in the worker.
container	Run the worker in a Docker image.
excludes	Paths to exclude from working_dir.

Working directories

working_dir packages a local directory and ships it to every worker. Workers cd into the directory before running tasks, so relative imports and file paths work.

runtime_env = {"working_dir": "./project", "excludes": [".git", "*.pyc"]}

For larger projects, host the directory on S3 or GCS and reference the URI:

runtime_env = {"working_dir": "s3://my-bucket/project.zip"}

Caching

Ray caches resolved environments per node. The same set of pip packages is installed once per node; subsequent tasks reuse the venv.

Container runtime envs

runtime_env = {
    "container": {
        "image": "rayproject/ray-ml:2.43.0-py311",
        "worker_path": "/usr/local/bin/python",
    }
}

Container runtime envs require the cluster to have container runtime support enabled (such as Podman or singularity).

Best practices

Pin versions explicitly. runtime_env={"pip": ["transformers"]} may resolve to different versions over time and across nodes; transformers==4.38.0 is reproducible.

Avoid setting working_dir on every task; it re-uploads (from cache) on every run. Set it once at ray.init time when possible.

Next steps

Configure

Cluster-wide configuration.

Cross-language

Mixing Python with Java and C++.