Python version from `.python-version` is not overridden by the one of the session

[paduszyk]

Current Behavior

In my project, I have a .python-version file to pin a version for development and CI:

# .python-version
3.14

and noxfile.py:

from __future__ import annotations

import nox

nox.options.default_venv_backend = "uv"


@nox.session(requires=["uv"])
@nox.parametrize(
    "python",
    [
        "3.10",
        "3.11",
        "3.12",
        "3.13",
        "3.14",
    ],
)
def pytest(session: nox.Session) -> None:
    session.run_install(
        "uv",
        "sync",
        "--no-dev",
        "--group=pytest",
        "--frozen",
        env={
            "UV_PROJECT_ENVIRONMENT": session.virtualenv.location,
        },
    )
    session.run("pytest")

I noticed that Nox creates the environments based on Python 3.14 only. If I remove the .python-version file, everything works as expected, i.e. the respective Python versions are installed and tested.

Expected Behavior

Nox should not care about the .python-version file and enforce the Python version specified by the session's parameter.

Steps To Reproduce

1. Run nox with .python-version (with 3.14 for a reference).
2. Check .nox/ contents — Python 3.14 is found in each environment.
3. rm -rf .nox/.
4. rm .python-version.
5. Run nox again.
6. Check .nox/ contents — now the Python versions are as expected.

Environment

- OS:
- Python:
- Nox:

Anything else?

A workaround:

@nox.session(requires=["uv"])
@nox.parametrize(
    "python",
    [
        "3.10",
        "3.11",
        "3.12",
        "3.13",
        "3.14",
    ],
)
def pytest(session: nox.Session, python: str) -> None:  # 'python' as explicit parameter
    session.run_install(
        "uv",
        "sync",
        f"--python={python}",  # the proper version installed via uv
        "--no-dev",
        "--group=pytest",
        "--frozen",
        env={
            "UV_PROJECT_ENVIRONMENT": session.virtualenv.location,
        },
    )
    session.run("pytest")

[henryiii]

I think this is because you are manually running uv sync? It's replacing the interpreter we install with a new one, I believe.

[RazerM]

The recipe at https://nox.thea.codes/en/stable/cookbook.html#using-a-lockfile is up to date, although could use --active instead:

@@ -1,3 +1,5 @@
 @nox.session(venv_backend="uv")
 def tests(session: nox.Session) -> None:
     """
@@ -9,6 +11,6 @@
         "--extra=test",
         "--no-default-extras",
         f"--python={session.virtualenv.location}",
-        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
+        "--active",
     )
     session.run("pytest", *session.posargs)

FWIW I prefer setting UV_PROJECT_ENVIRONMENT and UV_PYTHON in the session environment and then uv sync "just works":

@@ -1,16 +1,18 @@
-import nox_uv
-
 @nox.session(venv_backend="uv")
 def tests(session: nox.Session) -> None:
     """
     Run the unit and regular tests.
     """
+    uv_env(session)
     session.run_install(
         "uv",
         "sync",
         "--extra=test",
         "--no-default-extras",
-        f"--python={session.virtualenv.location}",
-        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
     )
     session.run("pytest", *session.posargs)
+
+
+def uv_env(session: nox.Session) -> None:
+    session.env["UV_PROJECT_ENVIRONMENT"] = session.virtualenv.location
+    session.env["UV_PYTHON"] = session.virtualenv.location

This is almost what nox-uv does, except nox-uv allows uv to recreate the virtual environment if a session does not request a specific Python version, as is the case for the tests example session above.

Consider:

• There is a .python-version file with 3.12
• nox is run with Python 3.11 (e.g. uvx --python 3.11 nox or uvx nox --force-python 3.11)
• nox will create .nox/tests using 3.11
• nox-uv calls uv sync without UV_PYTHON, so uv reads .python-version and recreates the virtual environment using 3.12
• This is probably not what the user wanted to happen.

[henryiii]

Would this make sense, then?

diff --git a/nox/virtualenv.py b/nox/virtualenv.py
index f7bc193..d6270bd 100644
--- a/nox/virtualenv.py
+++ b/nox/virtualenv.py
@@ -595,7 +595,12 @@ class VirtualEnv(ProcessEnv):
         if venv_backend not in {"virtualenv", "venv", "uv"}:
             msg = f"venv_backend {venv_backend!r} not recognized"
             raise ValueError(msg)
-        super().__init__(env={"VIRTUAL_ENV": self.location, "CONDA_PREFIX": None})
+        env = {"VIRTUAL_ENV": self.location, "CONDA_PREFIX": None}
+        if self._venv_backend == "uv":
+            env["UV_PROJECT_ENVIRONMENT"] = self.location
+            if self.interpreter is not None:
+                env["UV_PYTHON"] = self.location
+        super().__init__(env=env)

     def _clean_location(self) -> bool:
         """Deletes any existing virtual environment"""

[RazerM]

@henryiii I think that would be great to have implemented in nox directly.

I think it would be better to set UV_PYTHON even if self.interpreter is None, otherwise a uv sync command can change the venv out from under nox with a different Python version.