Latest Results
Ignore global Python pins when incompatible with `requires-python` (#15473)
<!--
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
@zanieb in #14916 found an interesting bug. Global pin is the user
preference across projects, but if the project locally has a local pin,
it should be an authoritative constraint and end up with error. This
avoids blocking new projects that intentionally require a newer Python
version than the user’s global default. We still error on a local
`.python-version` inside the project to preserve explicit, repo-scoped
intent.
* Explicit `--python` → Always wins regardless of constraints
* Local `.python-version` → Project-scoped, errors on conflict
* Global `.python-version` → User preference, ignored if conflicts with
project. Global pins are suggestions that can be overridden by project
requirements
* Project `requires-python` → Fallback when no pins exist
Implementation :
* If a global `~/.config/uv/.python-version` conflicts with a project
`requires-python`, we ignore the pin and use the project requirement
* If a local project `.python-version` conflicts, we error, with
guidance to update the pin
* Explicit `--python` continues to override both
Now, global pins are suggestions that can be overridden by project
requirements, rather than hard constraints that block project setup.
## Test Plan
A new has been added in `sync_python_version()` along with manual
testing :
```
harshps22ugp@lab:~/projects/uv$ target/debug/uv python pin --global 3.10
Pinned `/home/harshps22ugp/.config/uv/.python-version` to `3.10`
harshps22ugp@lab:~/projects/uv$ mkdir -p /tmp/uv-global-pin && cd /tmp/uv-global-pin
harshps22ugp@lab:/tmp/uv-global-pin$ cat > pyproject.toml <<'EOF'
> [project]
> name = "project"
> version = "0.1.0"
> requires-python = ">=3.11"
> dependencies = ["anyio==3.7.0"]
> EOF
harshps22ugp@lab:/tmp/uv-global-pin$ /home/harshps22ugp/projects/uv/target/debug/uv sync
Using CPython 3.13.5
Creating virtual environment at: .venv
Resolved 4 packages in 276ms
Prepared 3 packages in 149ms
░░░░░░░░░░░░░░░░░░░░ [0/3] Installing wheels... warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
If the cache and target directories are on different filesystems, hardlinking may not be supported.
If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Installed 3 packages in 35ms
+ anyio==3.7.0
+ idna==3.10
+ sniffio==1.3.1
harshps22ugp@lab:/tmp/uv-global-pin$ . .venv/bin/activate
(project) harshps22ugp@lab:/tmp/uv-global-pin$ python -V
Python 3.13.5
(project) harshps22ugp@lab:/tmp/uv-global-pin$
```
No error was thrown!
---------
Co-authored-by: Zanie Blue <contact@zanie.dev> Active Branches
#177350%
#178250%
#176510%
© 2026 CodSpeed Technology