uv python version determination and recommendations for Coppy projects

[rsyring]

For reference: https://docs.astral.sh/uv/concepts/python-versions/

Experiments

No python's in path other than system installed (mise deactivated):

 ❯ uv --verbose run python --version
DEBUG uv 0.7.17
DEBUG No project found; searching for Python interpreter
DEBUG No Python version file found in ancestors of working directory: /tmp/uv
DEBUG Searching for default Python interpreter in virtual environments, managed installations, or search path
DEBUG Searching for managed installations at `/home/rsyring/.local/share/uv/python`
DEBUG Found `cpython-3.12.3-linux-x86_64-gnu` at `/usr/bin/python3` (first executable in the search path)
DEBUG Using Python 3.12.3 interpreter at: /usr/bin/python3
DEBUG Running `python --version`
DEBUG Spawned child 120728 in process group 120724
Python 3.12.3
DEBUG Command exited with code: 0

Activate mise:

 ❯ printenv-path
/home/rsyring/.local/share/mise/installs/python/3.12.10/bin
/home/rsyring/.local/share/mise/installs/ubi-astral-sh-uv/0.7.17
/shared/apps/cargo/bin
/shared/bin
/home/rsyring/bin
/home/rsyring/.local/bin
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin
/usr/games
/usr/local/games
/snap/bin

 ❯ uv --verbose run python --version 2>&1 | grep -P 'Found|Using'
DEBUG Found `cpython-3.12.10-linux-x86_64-gnu` at `/home/rsyring/.local/share/mise/installs/python/3.12.10/bin/python` (first executable in the search path)
DEBUG Using Python 3.12.10 interpreter at: /home/rsyring/.local/share/mise/installs/python/3.12.10/bin/python

Managed install(s):

 ❯ uv python install 3.12
Installed Python 3.12.11 in 4.81s
 + cpython-3.12.11-linux-x86_64-gnu

 ❯ uv --verbose run python --version 2>&1 | grep -P 'Found|Using'
DEBUG Found managed installation `cpython-3.12.11-linux-x86_64-gnu`
DEBUG Found `cpython-3.12.11-linux-x86_64-gnu` at `/home/rsyring/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12` (managed installations)
DEBUG Using Python 3.12.11 interpreter at: /home/rsyring/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12

uv prefers the latest version, install order doesn't matter:

 ❯ uv python install 3.11 3.13
Installed 2 versions in 8.61s
 + cpython-3.11.13-linux-x86_64-gnu
 + cpython-3.13.5-linux-x86_64-gnu

 ❯ uv --verbose run python --version 2>&1 | grep -P 'Found|Using'
DEBUG Found managed installation `cpython-3.13.5-linux-x86_64-gnu`
DEBUG Found `cpython-3.13.5-linux-x86_64-gnu` at `/home/rsyring/.local/share/uv/python/cpython-3.13.5-linux-x86_64-gnu/bin/python3.13` (managed installations)
DEBUG Using Python 3.13.5 interpreter at: /home/rsyring/.local/share/uv/python/cpython-3.13.5-linux-x86_64-gnu/bin/python3.13

uv project init and then .python-version is present and controls the version:

 ❯ uv init -p 3.12
Initialized project `uv`

 ❯ cat .python-version
3.12

 ❯ grep requires pyproject.toml 
requires-python = ">=3.12"

 ❯ uv --verbose run python --version 2>&1
DEBUG uv 0.7.17
DEBUG Found project root: `/tmp/uv`
DEBUG No workspace root found, using project root
DEBUG Discovered project `uv` at: /tmp/uv
DEBUG Acquired lock for `/tmp/uv`
DEBUG Reading Python requests from version file at `/tmp/uv/.python-version`
DEBUG Using Python request `3.12` from version file at `.python-version`
DEBUG Checking for Python environment at `.venv`
DEBUG Searching for Python 3.12 in managed installations or search path
DEBUG Searching for managed installations at `/home/rsyring/.local/share/uv/python`
DEBUG Skipping managed installation `cpython-3.13.5-linux-x86_64-gnu`: does not satisfy `3.12`
DEBUG Found managed installation `cpython-3.12.11-linux-x86_64-gnu`
DEBUG Found `cpython-3.12.11-linux-x86_64-gnu` at `/home/rsyring/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12` (managed installations)
Using CPython 3.12.11
Creating virtual environment at: .venv
DEBUG Assessing Python executable as base candidate: /home/rsyring/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12
DEBUG Using base executable for virtual environment: /home/rsyring/.local/share/uv/python/cpython-3.12.11-linux-x86_64-gnu/bin/python3.12
DEBUG Released lock at `/tmp/uv-1da81efdbc706ccf.lock`
DEBUG Acquired lock for `.venv`
DEBUG Using request timeout of 30s
DEBUG Found static `pyproject.toml` for: uv @ file:///tmp/uv
DEBUG No workspace root found, using project root
DEBUG Existing `uv.lock` satisfies workspace requirements
Resolved 1 package in 0.78ms
DEBUG Using request timeout of 30s
Audited in 0.00ms
DEBUG Released lock at `/tmp/uv/.venv/.lock`
DEBUG Using Python 3.12.11 interpreter at: /tmp/uv/.venv/bin/python
DEBUG Running `python --version`
DEBUG Spawned child 125074 in process group 125069
Python 3.12.11
DEBUG Command exited with code: 0

Once the .venv exists, it takes precedence:

 ❯ uv --verbose run python --version 2>&1 | grep -P 'Using Python'
DEBUG Using Python request `3.12` from version file at `.python-version`
DEBUG Using Python 3.12.11 interpreter at: /tmp/uv/.venv/bin/python3

If .python-version is gone, then pyproject.toml version is used:

 ❯ rm .python-version 


 ❯ uv --verbose run python --version 2>&1 | grep -P 'Using Python'
DEBUG Using Python request `>=3.12` from `requires-python` metadata
DEBUG Using Python 3.12.11 interpreter at: /tmp/uv/.venv/bin/python3

If pyproject.toml version changes, it takes precedence over an incompatible .venv python:

 ❯ vim pyproject.toml && grep requires pyproject.toml
requires-python = ">=3.13"

 ❯ uv --verbose run python --version 2>&1 
( output manually filtered)
DEBUG Using Python request `>=3.13` from `requires-python` metadata
DEBUG Checking for Python environment at `.venv`
DEBUG The project environment's Python version does not satisfy the request: `Python >=3.13`
DEBUG Searching for Python >=3.13 in managed installations or search path
DEBUG Found managed installation `cpython-3.13.5-linux-x86_64-gnu`
Using CPython 3.13.5
Removed virtual environment at: .venv
Creating virtual environment at: .venv

DEBUG Ignoring existing lockfile due to change in Python requirement: `>=3.12` vs. `>=3.13`
DEBUG Using Python 3.13.5 interpreter at: /tmp/uv/.venv/bin/python
Python 3.13.5

Downgrading with the .venv already in place won't change the version used:

 ❯ vim pyproject.toml && grep requires pyproject.toml
requires-python = ">=3.11"

 ❯ uv --verbose run python --version 2>&1
DEBUG The project environment's Python version satisfies the request: `Python >=3.11`
DEBUG Using Python 3.13.5 interpreter at: /tmp/uv/.venv/bin/python3
Python 3.13.5

Removing the .venv results in a new 3.13 .venv b/c uv prefers the latest managed install:

❯ rm -rf .venv/

❯ uv --verbose run python --version 2>&1 | grep -P 'Using Python'
DEBUG Using Python request `>=3.11` from `requires-python` metadata
DEBUG Using Python 3.13.5 interpreter at: /tmp/uv/.venv/bin/python

A more restrictive pyproject.toml version will result in an updated .venv:

 ❯ vim pyproject.toml && grep requires pyproject.toml
requires-python = "~=3.12.5"

 ❯ uv --verbose run python --version 2>&1 | grep -P 'Using Python'
DEBUG Using Python request `>=3.12.5, <3.13` from `requires-python` metadata
DEBUG Using Python 3.12.11 interpreter at: /tmp/uv/.venv/bin/python

Specifying UV_PYTHON is also an option:

 ❯ vim pyproject.toml && grep requires pyproject.toml
requires-python = ">=3.12"

 ❯ UV_PYTHON=3.13 uv --verbose run python --version 2>&1 | grep -P 'Python'
DEBUG Using Python request `3.13` from explicit request
DEBUG Checking for Python environment at `.venv`
DEBUG The project environment's Python version does not satisfy the request: `Python 3.13`
DEBUG Searching for Python 3.13 in managed installations or search path
Using CPython 3.13.5
DEBUG Using Python 3.13.5 interpreter at: /tmp/uv/.venv/bin/python
Python 3.13.5

Recommendations

Given:

• It's desirable to avoid specifying the version of Python being used in more than one place.
• When mise is activated, the venv is added to the path giving direct access to the installed python bin and other uv installed python deps.
• Running uv without having to run mise first is desirable
• Scenarios requiring running Python in mise but not in uv, i.e. mise exec -- python --version, can be ignored
• Avoiding .requires-python can be beneficial to avoid integrations taking automatic actions when they aren't desirable (Here's looking at you Cloudflare Pages builder). It also avoids having to specify the 'idomatic" setting in mise.toml (nit).
• Applications are likely to want to specify a minor version of Python, e.g. ~=3.12.5 while libraries might want to be more flexible, e.g. >=3.10.

Then:

• Coppy projects:
  • SHOULD use uv for all it's Python needs.
  • It's NOT RECOMMENDED to rely on mise to install or manage Python tooling
  • Mise SHOULD be configured to create/activate a venv using uv.
• Applications:
  • SHOULD specify a more restrictive requires_python in pyproject.toml, e.g. ~=3.12.5.
  • CI and deployment tools SHOULD use uv to prep Python and the venv thereby ensuring the correct Python version is installed OR use tooling that respects requires_python to setup Python.
• Libraries
  • MAY specify a less restrictive requires_python
  • MAY add a .requires-python file or add UV_PYTHON= to mise.toml to help homogenize developer's default environments
  • SHOULD add CI coverage for each minor Python version supported by requires_python

[rsyring]

I guess I must have missed something in my analysis. I just did a fresh coppy project and saw:

 ❯ mise trust
mise trusted /home/rsyring/projects/pyapp3-copier-demo
mise creating venv with uv at: ~/.cache/uv-venvs/pyapp3-copier-demo
Using CPython 3.12.11 interpreter at: /home/rsyring/.local/share/mise/installs/python/3.12.11/bin/python
warning: The requested interpreter resolved to Python 3.12.11, which is incompatible with the project's Python requirement: `==3.13.*` (from `project.requires-python`)
Creating virtual environment at: /home/rsyring/.cache/uv-venvs/pyapp3-copier-demo
Activate with: source /home/rsyring/.cache/uv-venvs/pyapp3-copier-demo/bin/activate

When I removed the venv and ran uv manually, uv created a 3.13.5 venv.

I then removed the venv again, and had mise create the venv. That time, it was back to the 3.12 and the message above.

Conclusion: mise must be passing the python version explicitly to the uv venv created command. :o/

[rsyring]

I didn't realize this, but apparently Mise already solved syncing UV and Mise's python version by exporting UV_PYTHON:

https://mise.jdx.dev/lang/python.html#python.uv_venv_auto

The legacy true value (will be deprecated in a future release) is treated like "create|source", with one difference: When using this, mise also exports UV_PYTHON to force uv to use the python version managed by mise.

But, as indicated, they are getting rid of that feature. I wonder why and what they are assuming the intended replacement will be.

[rsyring]

Mise's recommendation is at: https://mise.jdx.dev/lang/python.html#mise-uv (towards the bottom):

[tools]
python = "3.12"

[env]
UV_PYTHON = { value = "{{ tools.python.path }}", tools = true }

[rsyring]

We don't want to do the full path like the mise docs recommend. In my test, because that gives UV a full path to the Mise Python interpreter:

• uv works fine for uv add etc which are project commands.
• uv pip no longer recognizes the venv though, even with VIRTUAL_ENV set. It will only see the venv when the Python interpreter is the bin from the venv's /bin.

 ❯ echo $UV_PYTHON
/home/rsyring/.local/share/mise/installs/python/3.12.13

 ❯ echo $VIRTUAL_ENV
/home/rsyring/.cache/uv-venvs/coppy-pkg

 ❯ uv pip freeze | head -n 3
Using Python 3.12.13 environment at: /home/rsyring/.local/share/mise/installs/python/3.12.13
pip @ file:///build/pip-26.0.1-py3-none-any.whl


 ❯ UV_PYTHON= uv pip freeze | head -n 3
Using Python 3.12.11 environment at: /home/rsyring/.cache/uv-venvs/coppy-pkg
annotated-types==0.7.0
anyio==4.13.0
argcomplete==3.6.3

If we need to tell UV to use the mise python, it can be done by version:

[env]
_.python.venv.create = true
UV_PYTHON = { value = "{{ tools.python[1].version }}", tools = true }

[tools]
python = ['3.12', '3.13']

But the lookup is then by PATH and it's possible you have a different venv in your path that has the python version you are using.

So, what we really want is to direct uv to the mise managed venv's python:

UV_PROJECT_ENVIRONMENT = "{{ exec(command='tasks/mise-uv-init.py' }}" #, cache_key='proj-env', cache_duration='1h') | trim }}"
_.python.venv.path = '{{ env.UV_PROJECT_ENVIRONMENT }}'
_.python.venv.create = true

# Configure uv to use the mise managed venv's python so that uv doesn't have to walk PATH to find
# the bin.  That can be problematic if you have another venv or python on the path and uv finds the
# wrong one.
UV_PYTHON = "{{ env.UV_PROJECT_ENVIRONMENT }}/bin/python"