Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

docs: UV_LINK_MODE=copy note for the nltk pathsec hardlink refusal (#406)

Christoph Stadlbauer5ccb1a72fbda
diff --git a/README.md b/README.md
index bbed9ab..c79eaa9 100755
--- a/README.md
+++ b/README.md
@@ -118,6 +118,8 @@ uv pip install leann
# CPU-only (Linux): use the `cpu` extra (e.g. `leann[cpu]`)
```
+> **Linux note:** if a later `leann build` fails with `Security Violation [pathsec.open]: refusing multiply-linked file`, reinstall with `UV_LINK_MODE=copy uv pip install --reinstall ...` (or `UV_LINK_MODE=copy uv tool install --reinstall ...`) - uv's default hardlink installs trip nltk's hardened file loader bundled with llama-index. Details in the [FAQ](docs/faq.md).
+
<!--
> Low-resource? See "Low-resource setups" in the [Configuration Guide](docs/configuration-guide.md#low-resource-setups). -->
diff --git a/docs/faq.md b/docs/faq.md
index c469a91..a90dfb2 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -56,3 +56,23 @@ npm install -g @lmstudio/sdk
```
See [Configuration Guide: LM Studio Auto-Detection](configuration-guide.md#lm-studio-auto-detection-optional) for details.
+
+## 5. `leann build` fails with `Security Violation [pathsec.open]: refusing multiply-linked file` (Linux)
+
+uv installs packages by **hardlinking** files from its cache into the environment by default. Recent nltk releases ship a hardened file loader (`nltk/pathsec.py`) that refuses to open multiply-linked files (`st_nlink > 1`, CWE-59 guard) - and llama-index, which LEANN uses for document parsing, loads its bundled nltk stopwords through exactly that path. The result on an uv-installed LEANN:
+
+```text
+PermissionError: Security Violation [pathsec.open]: refusing multiply-linked file
+'.../site-packages/llama_index/core/_static/nltk_cache/corpora/stopwords/english' (st_nlink=2);
+a hardlink can point at an outside-root inode (CWE-59)
+```
+
+**Fix:** reinstall with copy mode so no hardlinks are created:
+
+```bash
+UV_LINK_MODE=copy uv pip install --reinstall leann
+# or, for the global CLI/MCP install:
+UV_LINK_MODE=copy uv tool install --reinstall leann-core --with leann
+```
+
+`--reinstall` matters: without it uv leaves the already-hardlinked packages in place (satisfied requirements are skipped, and `uv tool install` refuses to overwrite an existing tool), so the error persists. pip installs are unaffected (pip copies by default).