[docs] Add guidance for matching Ray and Python versions with uv envi… (#56597)

**docs: Add important note about using `uv run --active` to avoid Python
version mismatch errors**

- Added best practices for launching Ray applications with uv.

<!-- Thank you for your contribution! Please review
https://github.com/ray-project/ray/blob/master/CONTRIBUTING.rst before
opening a pull request. -->

<!-- Please add a reviewer to the assignee section when you create a PR.
If you don't have the access to it, we will shortly find a reviewer and
assign them to your PR. -->

## Why are these changes needed?

This change adds a prominent note to the dependency management
documentation, warning users to use `uv run --active` to avoid Python
version mismatches and related runtime errors when launching Ray
applications. This addresses a common pitfall and improves the developer
experience.

## Related issue number

Closes #56583

## Checks

- [x] I've signed off every commit (by using the -s flag, i.e., `git
commit -s`) in this PR.
- [x] I've run `scripts/format.sh` to lint the changes in this PR.
- [x] I've included any doc changes needed for
https://docs.ray.io/en/master/.
- [x] I've added any new APIs to the API Reference. For example, if I
added a
method in Tune, I've added it in `doc/source/tune/api/` under the
           corresponding `.rst` file.
- [x] I've made sure the tests are passing. Note that there might be a
few flaky tests, see the recent failures at https://flakey-tests.ray.io/
- Testing Strategy
   - [x] This PR only updates documentation; no code changes to test.

---------

Signed-off-by: jitesh majety <[email protected]>
Signed-off-by: Philipp Moritz <[email protected]>
Co-authored-by: jitesh majety <[email protected]>
Co-authored-by: Philipp Moritz <[email protected]>
Signed-off-by: elliot-barn <[email protected]>

Author: 2 people

doc/source/ray-core/handling-dependencies.rst

@@ -377,6 +377,11 @@ run a Ray Serve application with `uv run serve run app:main`.
 
 **Best Practices and Tips:**
 
+- If you are running on a Ray Cluster, the Ray and Python versions of your uv environment must be the same as the Ray and Python versions of your cluster or you will get a version mismatch exception. There are multiple ways to solve this:
+
+  1. If you are using ephemeral Ray clusters, run the application on a cluster with the right versions.
+  2. If you need to run on a cluster with a different versions, consider modifying the versions of your uv environment by updating the `pyproject.toml` file or by using the `--active` flag with `uv run` (i.e., `uv run --active main.py`).
+
 - Use `uv lock` to generate a lockfile and make sure all your dependencies are frozen, so things won't change in uncontrolled ways if a new version of a package gets released.
 
 - If you have a requirements.txt file, you can use `uv add -r requirement.txt` to add the dependencies to your `pyproject.toml` and then use that with uv run.