uv integration doesn't work with Ray Client (gRPC)

[preneond]

The Bug

Ray’s uv integration (RAY_RUNTIME_ENV_HOOK) does not work with Ray Client connections via ray.init("ray://..."). The hook is ignored during runtime environment creation, preventing users from using uv as package management with Ray Client.

Current behavior:

• Ray Jobs API (ray job submit -- uv run script.py): uv automatically installs dependencies from pyproject.toml/uv.lock, including packages from custom PyPI indexes
• Ray Client (ray.init("ray://...")): uv integration doesn’t work, forcing users to manually manage dependencies or switch to detached mode with Jobs API

Expected Behavior

When connecting to a Ray cluster via Ray Client, if uv is installed and RAY_RUNTIME_ENV_HOOK is configured on cluster nodes, dependencies should be automatically installed using uv sync from pyproject.toml and uv.lock files in the working_dir — just like the Ray Jobs API does.

Reproduction

Cluster Setup

• RAY_RUNTIME_ENV_HOOK=ray._private.runtime_env.uv_runtime_env_hook.hook set on head and worker nodes
• uv installed and available on all nodes
• Custom PyPI credentials configured via environment variables

Test Script

import ray

ray.init("ray://my-cluster:10001")

@ray.remote
def test_task():
    import my_internal_package  # Package from custom PyPI index
    return True

result = ray.get(test_task.remote())
ray.shutdown()

Error

INFO packaging.py:380 -- Pushing file package 'gcs://_ray_pkg_25e8b7d5a9b91305.zip' (1.99MiB) to Ray cluster...
INFO packaging.py:393 -- Successfully pushed file package 'gcs://_ray_pkg_25e8b7d5a9b91305.zip'.

ray.exceptions.RayTaskError(ModuleNotFoundError): ray::test_task() (pid=1628970, ip=X.XXX.X.XXX)
  File "test_ray_uv.py", line 11, in test_task
ModuleNotFoundError: No module named 'my_internal_package'

What’s happening: The working_dir uploads successfully , but dependencies from pyproject.toml/uv.lock are never installed

Environment

• Ray: 2.49.0
• Python: 3.12.9
• uv: 0.5.x
• Connection: Ray Client (gRPC via ray.init("ray://..."))
• Deployment: Kubernetes (RayCluster CRD)

Impact

This blocks teams using:

• Custom PyPI indexes (e.g., JFrog Artifactory) with authentication
• uv.lock files for reproducible builds
• Interactive/attached workflows (notebooks, CI/CD)

Current workarounds:

1. Use Ray Jobs API → forces detached mode only
2. Pre-bake dependencies into Docker images → loses uv’s speed and flexibility

Related Issues

• #51196 — Runtime env hooks with Ray Client
• #50961 — Related stability issues (my comment)

Additional Context

The Ray documentation only covers uv with the Ray Jobs API, with no mention of Ray Client support.

I’m not sure if there’s a workaround for this. Any guidance would be appreciated, or please consider this a feature request if uv + Ray Client support isn’t currently planned.

[RunLLM]

Ray’s uv integration (RAY_RUNTIME_ENV_HOOK) does not work with Ray Client connections via ray.init(“ray://…”); the hook is ignored, so dependencies from pyproject.toml/uv.lock are not installed on workers, leading to ModuleNotFoundError for packages not preinstalled. This is a known limitation: uv integration is only supported with the Ray Jobs API, not Ray Client, as confirmed by both the Ray documentation and GitHub issue #57991.

There is currently no workaround to enable uv-based dependency management with Ray Client; users must either use the Ray Jobs API (detached mode) or pre-bake dependencies into Docker images. The Ray team has acknowledged this as a feature request, but as of now, uv + Ray Client is not supported and is not documented as such. Would you like more detail on possible workarounds or updates on this feature?

Sources:

• GitHub issue #57991: uv integration doesn’t work with Ray Client (gRPC)

Hint: Mention @RunLLM in the post for followups.

[eoakes]

@preneond can you please file a request for this as an issue on the Ray repo?