Issues with setting up runtime environment using "uv run"

Ray Core
4

The error (raylet) ModuleNotFoundError: No module named 'ray' on worker startup means the Ray package is not installed in the Python environment that the worker process is using. This is a common issue when Ray creates a new virtual environment (e.g., .venv) for the runtime environment, but the Ray package itself is not present in that environment (see discussion, see also).

To fix this, ensure that:

  • The Ray package is included in your runtime environment dependencies (e.g., in your pyproject.toml, requirements.txt, or runtime_env pip/uv list).
  • If using uv, make sure ray is listed as a dependency so it is installed in the worker’s environment.
  • Avoid situations where Ray creates a new .venv that does not inherit the parent environment’s packages.

Example fix (for runtime_env):

runtime_env = {
    "pip": ["ray==2.52.0", ...],  # add other dependencies as needed
    ...
}

Or, if using uv, ensure ray is in your pyproject.toml dependencies.

Would you like more detailed troubleshooting steps?

Sources:

Hint: Mention @RunLLM in the post for followups.