From 2db1630f54767fbbcef05cfc2613456344cacba2 Mon Sep 17 00:00:00 2001
From: Jay Qi <2721979+jayqi@users.noreply.github.com>
Date: Tue, 27 May 2025 12:23:29 -0400
Subject: [PATCH] Add documentation about Python versions to Tools concept page
 (#7673)

<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:

- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->

## Summary

Add documentation about Python versions to Tools concept page

## Test Plan

N/A

---------

Co-authored-by: Jay Qi <jayqi@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
---
 docs/concepts/tools.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md
index c79527fd1..d5069e725 100644
--- a/docs/concepts/tools.md
+++ b/docs/concepts/tools.md
@@ -203,6 +203,19 @@ $ uvx --with <extra-package>==<version> <tool-package>
 If the requested version conflicts with the requirements of the tool package, package resolution
 will fail and the command will error.
 
+## Python versions
+
+Each tool environment is linked to a specific Python version. This uses the same Python version
+[discovery logic](./python-versions.md#discovery-of-python-versions) as other virtual environments
+created by uv, but will ignore non-global Python version requests like `.python-version` files and
+the `requires-python` value from a `pyproject.toml`.
+
+The `--python` option can be used to request a specific version. See the
+[Python version](./python-versions.md) documentation for more details.
+
+If the Python version used by a tool is _uninstalled_, the tool environment will be broken and the
+tool may be unusable.
+
 ## Tool executables
 
 Tool executables include all console entry points, script entry points, and binary scripts provided