From 3ffa8c334681d7dd58a1257b0d353ff1f506c280 Mon Sep 17 00:00:00 2001
From: Benjamin Sparks <b.sparks@alugha.com>
Date: Mon, 8 Sep 2025 10:32:33 +0200
Subject: [PATCH] uv: add manual entry

---
 doc/packages/index.md          |  1 +
 doc/packages/uv.section.md     | 22 ++++++++++++++++++++++
 doc/redirects.json             |  3 +++
 pkgs/by-name/uv/uv/package.nix | 11 +++++++++++
 4 files changed, 37 insertions(+)
 create mode 100644 doc/packages/uv.section.md

diff --git a/doc/packages/index.md b/doc/packages/index.md
index 35e2656ab670..623fbe357d54 100644
--- a/doc/packages/index.md
+++ b/doc/packages/index.md
@@ -32,5 +32,6 @@ urxvt.section.md
 vcpkg.section.md
 weechat.section.md
 xorg.section.md
+uv.section.md
 build-support.md
 ```
diff --git a/doc/packages/uv.section.md b/doc/packages/uv.section.md
new file mode 100644
index 000000000000..c26ef784d5b2
--- /dev/null
+++ b/doc/packages/uv.section.md
@@ -0,0 +1,22 @@
+# uv {#sec-uv}
+
+`uv` is an extremely fast Python package installer and resolver, written in Rust.
+It manages project dependencies and environments, with support for lockfiles, workspaces, and more.
+
+Due to `uv` being unaware that it is running on a NixOS system, by default, it will fetch dynamically-linked Python executables that will fail to run, as NixOS cannot run executables intended for generic Linux environments out of the box.
+To learn more on this, please visit
+https://nix.dev/guides/faq.html#how-to-run-non-nix-executables
+
+There are two ways to mitigate this:
+
+1. Provide `uv` with a statically-linked Python executable (ideally from `nixpkgs`) via the [`UV_PYTHON` environment variable](https://docs.astral.sh/uv/reference/environment/#uv_python). Alternatively, the `--python` flag can also be used, but this is easy to forget. It is also helpful to forbid `uv` from downloading any Python binaries via the [`UV_PYTHON_DOWNLOADS` environment variable](https://docs.astral.sh/uv/reference/environment/#uv_python_downloads) by setting it to `never`.
+These variables can be set in `shell.nix` and `.env` files, which can be redistributed with the project to ensure other NixOS machines can execute the project.
+
+2. Add `programs.nix-ld.enable = true` to your NixOS config. While functional, the previous option is to be preferred, as this is the "works on my machine" option, because redistributing Python projects that use `uv` to another NixOS machine that does not have `nix-ld` enabled will cause the same errors to occur.
+
+Additionally, there is the issue of modules from PyPI vendoring dynamically-linked libraries, such as `numpy`, which will also fail to work.
+This topic is not local to `uv`, but is deserving of documentation nonetheless.
+Setting `LD_LIBRARY_PATH` should be the solution of choice here. Either:
+
+1. Use `lib.makeLibraryPath` to set `LD_LIBRARY_PATH` from a `shell.nix`, e.g. `LD_LIBRARY_PATH = lib.makeLibraryPath [ pkgs.openssl pkgs.zlib pkgs.curl ]`
+2. (If you have already enabled `nix-ld`) set `LD_LIBRARY_PATH` to `NIX_LD_LIBRARY_PATH`. Be aware this is not a silver bullet solution, as this simply provides a list of commonly used libraries, as is shown in `nixos/modules/programs/nix-ld.nix`.
diff --git a/doc/redirects.json b/doc/redirects.json
index 80392ea35d39..0442248c3e3e 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -4594,6 +4594,9 @@
   "sec-interop.cylonedx-fod": [
     "index.html#sec-interop.cylonedx-fod"
   ],
+  "sec-uv": [
+    "index.html#sec-uv"
+  ],
   "module-system-module-argument-_prefix": [
     "index.html#module-system-module-argument-_prefix"
   ],
diff --git a/pkgs/by-name/uv/uv/package.nix b/pkgs/by-name/uv/uv/package.nix
index 0bfb67a0bdc9..9eacfafb9571 100644
--- a/pkgs/by-name/uv/uv/package.nix
+++ b/pkgs/by-name/uv/uv/package.nix
@@ -69,6 +69,17 @@ rustPlatform.buildRustPackage (finalAttrs: {
 
   meta = {
     description = "Extremely fast Python package installer and resolver, written in Rust";
+    longDescription = ''
+      `uv` manages project dependencies and environments, with support for lockfiles, workspaces, and more.
+
+      Due to `uv`'s (over)eager fetching of dynamically-linked Python executables,
+      as well as vendoring of dynamically-linked libraries within Python modules distributed via PyPI,
+      NixOS users can run into issues when managing Python projects.
+      See the Nixpkgs Reference Manual entry for `uv` for information on how to mitigate these issues:
+      https://nixos.org/manual/nixpkgs/unstable/#sec-uv.
+
+      For building Python projects with `uv` and Nix outside of nixpkgs, check out `uv2nix` at https://github.com/pyproject-nix/uv2nix.
+    '';
     homepage = "https://github.com/astral-sh/uv";
     changelog = "https://github.com/astral-sh/uv/blob/${finalAttrs.version}/CHANGELOG.md";
     license = with lib.licenses; [