From df086e8349f2b72d34196656e5b86a5c551e2d3b Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 7 Nov 2024 14:10:36 -0600 Subject: [PATCH] Add docs for `.python-version` file discovery (#8898) --- docs/concepts/python-versions.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index 23cedaceac21..59bfba36c0aa 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -49,6 +49,17 @@ By default, uv will automatically download Python versions if they cannot be fou This behavior can be [disabled with the `python-downloads` option](#disabling-automatic-python-downloads). +### Python version files + +The `.python-version` file can be used to create a default Python version request. uv searches for a +`.python-version` file in the working directory and each of its parents. Any of the request formats +described above can be used, though use of a version number is recommended for interopability with +other tools. + +A `.python-version` file can be created in the current directory with the `uv python pin` command. + +Discovery of `.python-version` files can be disabled with `--no-config`. + ## Installing a Python version uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows. @@ -91,20 +102,17 @@ $ uv python install pypy All of the [Python version request](#requesting-a-version) formats are supported except those that are used for requesting local interpreters such as a file path. -## Project Python versions - By default `uv python install` will verify that a managed Python version is installed or install the -latest version. +latest version. If a `.python-version` file is present, uv will install the Python version listed in +the file. A project that requires multiple Python versions may define a `.python-versions` file. If +present, uv will install all of the Python versions listed in the file. -However, a project may include a `.python-version` file specifying a default Python version. If -present, uv will install the Python version listed in the file. - -Alternatively, a project that requires multiple Python versions may also define a `.python-versions` -file. If present, uv will install all of the Python versions listed in the file. This file takes -precedence over the `.python-version` file. +## Project Python versions -uv will also respect Python requirements defined in a `pyproject.toml` file during project command -invocations. +uv will respect Python requirements defined in `requires-python` in the `pyproject.toml` file during +project command invocations. The first Python version that is compatible with the requirement will +be used, unless a version is otherwise requested, e.g., via a `.python-version` file or the +`--python` flag. ## Viewing available Python versions