Missing Documentation: uv

[dwt]

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.

[matdibu]

would this fit/work for your use case?

  shellHook = ''
    uv sync
    source .venv/bin/activate
    # uv add ... / uv pip install …
  '';

[dwt]

@matdibu If the project is pyproject.toml based (and possibly contains a uv.lock file) that is preferred and picks up the correct UV_PYTHON executable.

But the problem is that in my experiments, whenever a uv pip … command becomes necessary (or anything besides uv sync) this fails, because then uv tries to use the python binary and environment pointed to by UV_PYTHON directly, instead of the generated virtualenv, that would otherwise be used without that variable being set.

I am not yet sure if this is the default behavior of all commands or just of some commands, but definitely for uv pip …