Document nox-uv third party package

[johnthagen]

Related to

• Support for uv.lock #841

We think nox-uv is ready for greater visibility now that the 0.6.0 release is out.

• https://github.com/dantebben/nox-uv

We think this helps simplify common usage patterns of nox and uv.

[henryiii]

This needs to have the PEP 723 bits so it will work without needing to install nox-uv.

[johnthagen]

@henryiii Happy to. But how is PEP 723 supposed to work with Nox specifically (and invoking Nox sessions?). The tutorial seems to only mention how it can be used to install dependencies for sessions, not actually how to install nox and make noxfile.py runnable directly.

• https://nox.thea.codes/en/stable/tutorial.html#loading-dependencies-from-pyproject-toml-or-scripts

For nox-uv we'd define it like:

# /// script
# dependencies = ["nox-uv"]
# ///

from nox import Session
from nox_uv import session


@session
def hello(s: Session) -> None:
    print("Hello, Nox!")

uv run noxfile.py now "works" (it installs nox-uv which has a dependency on nox). But what is the expected workflow for allowing something like: uv run noxfile.py -s hello?

The way I personally use Nox is to define it as a development dependency in pyproject.toml and have uv lock a pinned version that all developers and CI use the same version:

• https://github.com/johnthagen/python-blueprint/blob/main/pyproject.toml#L42

But I'm open to PEP 723, but I can't find in the Nox docs how you are supposed to properly bootstrap Nox such that the CLI commands work.

[henryiii]

The full form would be this:

#!/usr/bin/env -S uv run -q

# /// script
# dependencies = ["nox", "nox-uv"]
# ///

import nox
import nox_uv


@nox_uv.session
def hello(s: nox.Session) -> None:
    print("Hello, Nox!")
    
if __name__ == "__main__":
    nox.main()

This enables all possible ways to run it:

• nox -s hello: Nox will check to see if the dependencies are met. If not, it makes an internal session with the dependencies, and runs itself from there
• uv run noxfile.py -s hello: Arguments work just fine
• pipx run noxfile.py -s hello: Any runner works
• ./noxfile.py -s hello: This will use uv run

Specifically, though, for plugins, the first one is most important, as it makes a nox plugin "just work" on all installs of nox, including brew/uv/uvx, etc. (IMO, you should not install nox as a library except for type checking, it's a CLI app, so uv tool install, etc).

[johnthagen]

@henryiii Thanks for the details! I actually think that this method should be documented in the Nox docs as well, but that's a separate thing.

Specifically, though, for plugins, the first one is most important, as it makes a nox plugin "just work" on all installs of nox, including brew/uv/uvx, etc. (IMO, you should not install nox as a library except for type checking, it's a CLI app, so uv tool install, etc).

Good to know that others work this way. I've always treated all CLI tools in my projects (Ruff, Mypy, Nox, etc) as needing to be pinned rather than global so that all users/contributors/CI always use the same version and to make everything reproducible.

Thanks for sharing this alternative workflow and let me know how the PR looks now.

[johnthagen]

@henryiii Are the CI failures unrelated? Not sure how a doc-only PR could trigger a coverage failure? Perhaps some dependencies aren't pinned?

[henryiii]

I think there might be "project-based tools" concept in uv in the future. For now, though, we are stuck with one or the other.

The failures are due to coveragepy/coveragepy#1983 which I haven't had time to fix yet. I'm working on #979 currently.

[henryiii]

• fix: hide new coverage warning on 3.14 #980

[johnthagen]

@henryiii Thanks for getting the CI green ✅ .

If you'd like any more changes let me know.