# uv integration doesn't work with Ray Client (gRPC)
**URL:** https://discuss.ray.io/t/uv-integration-doesnt-work-with-ray-client-grpc/23279
**Category:** Ray Client
**Created:** [October 28, 2025, 7:02pm UTC](https://discuss.ray.io/t/uv-integration-doesnt-work-with-ray-client-grpc/23279 "2025-10-28T19:02:31Z")
**Posts on this page:** 3
**Page:** 1
### Author:  [@preneond](https://discuss.ray.io/u/preneond)
#### Post date: [October 28, 2025, 7:02pm UTC](https://discuss.ray.io/t/uv-integration-doesnt-work-with-ray-client-grpc/23279/1 "2025-10-28T19:02:31Z")
## 🐛 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
```auto
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
```auto
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](https://github.com/ray-project/ray/issues/50961#issuecomment-3426367526))
## 📚 Additional Context
The [Ray documentation](https://docs.ray.io/en/master/ray-core/handling-dependencies.html#using-uv-for-package-management) 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.
---
### Author:  [@RunLLM](https://discuss.ray.io/u/RunLLM)
#### Post date: [October 28, 2025, 7:03pm UTC](https://discuss.ray.io/t/uv-integration-doesnt-work-with-ray-client-grpc/23279/2 "2025-10-28T19:03:19Z")
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](https://docs.ray.io/en/master/ray-core/handling-dependencies.html#using-uv-for-package-management) and [GitHub issue #57991](https://github.com/ray-project/ray/issues/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)](https://github.com/ray-project/ray/issues/57991)
Hint: Mention @RunLLM in the post for followups.
---
### Author:  [@eoakes](https://discuss.ray.io/u/eoakes)
#### Post date: [October 29, 2025, 5:30pm UTC](https://discuss.ray.io/t/uv-integration-doesnt-work-with-ray-client-grpc/23279/3 "2025-10-29T17:30:49Z")
@preneond can you please file a request for this as an issue on the Ray repo?