Add support for global `uv python pin` #12115

jtfmumm · 2025-03-11T14:52:22Z

These changes add support for

uv python pin 3.12 --global

This adds the specified version to a .python-version file in the user-level config directory. uv will now use the user-level version as a fallback if no version is found in the project directory or its ancestors.

Open question: is --global the correct parameter here? --user is more precise, but might not communicate the intent as clearly.

TODO: User documentation.

Closes #4972

crates/uv/tests/it/common/mod.rs

crates/uv/tests/it/python_pin.rs

crates/uv/tests/it/tool_install.rs

zanieb · 2025-03-11T17:48:53Z

crates/uv/tests/it/tool_install.rs

+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        // We should have a tool receipt
+        assert_snapshot!(fs_err::read_to_string(tool_dir.join("black").join("uv-receipt.toml")).unwrap(), @r###"
+        [tool]
+        requirements = [{ name = "black" }]
+        entrypoints = [
+            { name = "black", install-path = "[TEMP_DIR]/bin/black" },
+            { name = "blackd", install-path = "[TEMP_DIR]/bin/blackd" },
+        ]
+
+        [tool.options]
+        exclude-newer = "2024-03-25T00:00:00Z"
+        "###);
+    });


We don't capture the Python version in the receipt. This is actually relevant. What happens if the global Python version changes then you reinstall or upgrade? Test coverage for that would good. I think it's fine to respect the changed global default, personally.

I have a FIXME with some commented out new test code in this test for the reinstall case. This test code fails: currently uv doesn't respect the global on reinstall (and just uses the version originally used). Do we want this functionality for this PR?

Ah okay, thanks for clarifying.

I would expect

If I requested a version explicitly, e.g., uv tool install --python <version> I'd expect it to be recorded in the receipt and reused on reinstall

If I did not, I would expect the version to change on reinstall if the global default changed

However, I don't feel strongly about the latter point and if it's an entirely different model than what we're doing today then let's just leave it as-is and consider it separately (I'd open an issue to track it).

Either way, test coverage seems great.

crates/uv-python/src/version_files.rs

crates/uv-cli/src/lib.rs

zanieb · 2025-03-11T17:59:22Z

crates/uv-python/src/version_files.rs

-            return Ok(None);
+            // Not found in directory or its ancestors. Looking in user-level config.
+            return Ok(match user_uv_config_dir() {
+                Some(user_dir) => Self::discover_user_config(user_dir, options)


I wonder if we should co-locate this with the uv.toml? Like, if

uv/crates/uv-dirs/src/lib.rs

Line 140 in ba74b9e

pub fn system_config_file() -> Option<PathBuf> {

exists and a user-level config does not should we prefer that? I'm leaning away from it right now, but wanted to put the idea out there. Maybe can can consider a --system flag separately in the future once we have more feedback.

That's an interesting question. But I agree we should consider it separately from this PR.

samypr100 · 2025-03-12T02:05:32Z

These changes add support for
uv python pin 3.12 --global 
This adds the specified version to a .python-version file in the user-level config directory. uv will now use the user-level version as a fallback if no version is found in the project directory or its ancestors.

Open question: is --global the correct parameter here? --user is more precise, but might not communicate the intent as clearly.

TODO: User documentation.

Closes #4972

I do lean towards --global. For example, git uses --global, --local, and --system.

crates/uv-cli/src/lib.rs

crates/uv/tests/it/common/mod.rs

crates/uv-static/src/env_vars.rs

crates/uv/tests/it/python_pin.rs

zanieb · 2025-03-12T20:22:00Z

crates/uv/tests/it/python_pin.rs

+}
+
+#[test]
+fn python_pin_global_use_local_if_available() -> Result<()> {


I'd still just recommend combining this test with the one above and calling it python_pin_global since we tend to discuss the specific behavior we are testing in a comment above each invocation. This isn't blocking feedback though

zanieb

I think this should only require some brief docs in https://docs.astral.sh/uv/concepts/python-versions/#python-version-files

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.6.5` -> `0.6.9` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.6.9`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#069) [Compare Source](astral-sh/uv@0.6.8...0.6.9) ##### Enhancements - Use `keyring --mode creds` when `authenticate = "always"` ([#12316](astral-sh/uv#12316)) - Fail with specific error message when no password is present and `authenticate = "always"` ([#12313](astral-sh/uv#12313)) ##### Bug fixes - Add boolish value parser for `UV_MANAGED_PYTHON` flags ([#12345](astral-sh/uv#12345)) - Make deserialization non-fatal when assessing source tree revisions ([#12319](astral-sh/uv#12319)) - Use resolver-returned wheel over alternate cached wheel ([#12301](astral-sh/uv#12301)) ##### Documentation - Add experimental `--torch-backend` to the PyTorch guide ([#12317](astral-sh/uv#12317)) - Fix `#keyring-provider` references in alternative index docs ([#12315](astral-sh/uv#12315)) - Fix `--directory` path in examples ([#12165](astral-sh/uv#12165)) ##### Preview changes - Automatically infer the PyTorch index via `--torch-backend=auto` ([#12070](astral-sh/uv#12070)) ### [`v0.6.8`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#068) [Compare Source](astral-sh/uv@0.6.7...0.6.8) ##### Enhancements - Add support for enabling all groups by default with `default-groups = "all"` ([#12289](astral-sh/uv#12289)) - Add simpler `--managed-python` and `--no-managed-python` flags for toggling Python preferences ([#12246](astral-sh/uv#12246)) ##### Performance - Avoid allocations for default cache keys ([#12063](astral-sh/uv#12063)) ##### Bug fixes - Allow local version mismatches when validating lockfile ([#12285](astral-sh/uv#12285)) - Allow owned string when deserializing `requires-python` ([#12278](astral-sh/uv#12278)) - Make cache errors non-fatal in `Planner::build` ([#12281](astral-sh/uv#12281)) ### [`v0.6.7`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#067) [Compare Source](astral-sh/uv@0.6.6...0.6.7) ##### Python - Add CPython 3.14.0a6 - Fix regression where extension modules would use wrong `CXX` compiler on Linux - Enable FTS3 enhanced query syntax for SQLite See the [`python-build-standalone` release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250317) for more details. ##### Enhancements - Add support for `-c` constraints in `uv add` ([#12209](astral-sh/uv#12209)) - Add support for `--global` default version in `uv python pin` ([#12115](astral-sh/uv#12115)) - Always reinstall local source trees passed to `uv pip install` ([#12176](astral-sh/uv#12176)) - Render token claims on publish permission error ([#12135](astral-sh/uv#12135)) - Add pip-compatible `--group` flag to `uv pip install` and `uv pip compile` ([#11686](astral-sh/uv#11686)) ##### Preview features - Avoid creating duplicate directory entries in built wheels ([#12206](astral-sh/uv#12206)) - Allow overriding module names for editable builds ([#12137](astral-sh/uv#12137)) ##### Performance - Avoid replicating core-metadata field on `File` struct ([#12159](astral-sh/uv#12159)) ##### Bug fixes - Add `src` to default cache keys ([#12062](astral-sh/uv#12062)) - Discard insufficient fork markers ([#10682](astral-sh/uv#10682)) - Ensure `python pin --global` creates parent directories if missing ([#12180](astral-sh/uv#12180)) - Fix GraalPy abi tag parsing and discovery ([#12154](astral-sh/uv#12154)) - Remove extraneous script packages in `uv sync --script` ([#12158](astral-sh/uv#12158)) - Remove redundant `activate.bat` output ([#12160](astral-sh/uv#12160)) - Avoid subsequent index hint when no versions are available on the first index ([#9332](astral-sh/uv#9332)) - Error on lockfiles with incoherent wheel versions ([#12235](astral-sh/uv#12235)) ##### Rust API - Update `BaseClientBuild` to accept custom proxies ([#12232](astral-sh/uv#12232)) ##### Documentation - Make testpypi index explicit in example snippet ([#12148](astral-sh/uv#12148)) - Reverse and format the archived changelogs ([#12099](astral-sh/uv#12099)) - Use consistent commas around i.e. and e.g. ([#12157](astral-sh/uv#12157)) - Fix typos in MRE docs ([#12198](astral-sh/uv#12198)) - Fix double space typo ([#12171](astral-sh/uv#12171)) ### [`v0.6.6`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#066) [Compare Source](astral-sh/uv@0.6.5...0.6.6) ##### Python - Add support for dynamic musl Python distributions on x86-64 Linux ([#12121](astral-sh/uv#12121)) - Allow the experimental JIT to be enabled at runtime on Python 3.13 and 3.14 on Linux - Upgrade the build toolchain to LLVM 20, improving performance See the [`python-build-standalone` release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250311) for more details. ##### Enhancements - Add `--marker` flag to `uv add` ([#12012](astral-sh/uv#12012)) - Allow overriding module name for uv build backend ([#11884](astral-sh/uv#11884)) - Sync latest Python releases ([#12120](astral-sh/uv#12120)) - Use 'Upload' instead of 'Download' in publish reporter ([#12029](astral-sh/uv#12029)) - Add `[index].authenticate` allowing authentication to be required on an index ([#11896](astral-sh/uv#11896)) - Add support for Windows legacy scripts in `uv tool run` ([#12079](astral-sh/uv#12079)) - Propagate conflicting dependency groups when using `include-group` ([#12005](astral-sh/uv#12005)) - Show ambiguous requirements when `uv add` failed ([#12106](astral-sh/uv#12106)) ##### Performance - Cache workspace discovery ([#12096](astral-sh/uv#12096)) - Insert dependencies into fork state prior to fetching metadata ([#12057](astral-sh/uv#12057)) - Remove some allocations from `uv-auth` ([#12077](astral-sh/uv#12077)) ##### Bug fixes - Avoid considering `PATH` updated when the `export` is commented in the shellrc ([#12043](astral-sh/uv#12043)) - Fix `uv publish` retry on network failures ([#12041](astral-sh/uv#12041)) - Use a sized stream in `uv publish` to comply with WSGI PyPI server constraints ([#12111](astral-sh/uv#12111)) - Fix `uv python install --reinstall` when the version was not previously installed ([#12124](astral-sh/uv#12124)) ##### Preview features - Fix `uv_build` invocation ([#12058](astral-sh/uv#12058)) ##### Documentation - Quote versions string in `python-versions.md` ([#12112](astral-sh/uv#12112)) - Fix tool concept page headings ([#12053](astral-sh/uv#12053)) - Update the `[index].authenticate` docs ([#12102](astral-sh/uv#12102)) - Update versioning policy ([#11666](astral-sh/uv#11666)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

jtfmumm requested a review from zanieb March 11, 2025 14:52

jtfmumm temporarily deployed to release March 11, 2025 14:52 — with GitHub Actions Inactive

jtfmumm temporarily deployed to release March 11, 2025 15:30 — with GitHub Actions Inactive