Missing Documentation: uv

Describe the problem

The nixpkgs documentation mentions that the UV_PYTHON environment variable can be set to point to a nix provided python binary, to force uv to not download it's own python binaries.

While this seems to work for packaging in Nixpkgs, I am pretty sure it is the wrong advice for use in shell.nix or flake.nix based development environments, as uv tries to use that python binary directly, for all operations instead of using it to build a local virtualenv using that python binary and then installing everything in there.

What I have found is that I usually require something like this in my development environment (shell.nix used for brevity)

{
  pkgs ? import <nixpkgs> { },
}:

let
  python = pkgs.python3;
in
pkgs.mkShell {
  buildInputs = with pkgs; [
    hidapi
    python
    uv
    darwin.lsusb
  ];

  env = {
    UV_PYTHON_DOWNLOADS = "never";
  };

  shellHook = ''
    if [ ! -d .venv ]; then
        uv venv --python ${pkgs.lib.getExe python}
    fi
    source .venv/bin/activate
    # macos dependencies
    uv pip install pyhidapi pyusb pillow
  '';
}

Proposed solution

I may be missing something - but if I am not, then we should probably mention that for use in development environments setting `UV_PYTHON` is a bad idea and instead using the `shellHook` to prefix it with something like this is a much better idea:


  shellHook = ''
    if [ ! -d .venv ]; then
        uv venv --python ${pkgs.lib.getExe python}
    fi
    source .venv/bin/activate
    # uv sync / uv pip install …
  '';


This still has it's own problems, because the virtualenv is not refreshed / rebuilt if the python version changes, but it at least works initially.

I am seeking feedback here, to either find a better solution for development environment integration of `uv` or if there is none, I would like to provide an annex to the documentation that adds an example like this.

Notify maintainers

Note for maintainers: Please tag this issue in your pull request description. (i.e. Resolves #ISSUE.)

I assert that this issue is relevant for Nixpkgs

• I assert that this request is not already implemented in the latest NixOS or Nixpkgs manuals.
• I assert that this is not a duplicate of an existing documentation issue.
• I assert that I have read the NixOS Code of Conduct and agree to abide by it.

Is this issue important to you?

Add a 👍 reaction to issues you find important.

Read doc/packages/uv.section.md and review the current UV_PYTHON guidance against the development-environment behavior described here. Confirm with maintainers whether the shellHook example is the agreed approach, then update the section with the approved guidance and example; done when packaging and development use are clearly distinguished.