From 7bc6ccea19132abc1d4d888fab201735554b6b4c Mon Sep 17 00:00:00 2001
From: yangdx <gzdaniel@me.com>
Date: Sun, 9 Nov 2025 04:31:07 +0800
Subject: [PATCH] Add uv package manager support to installation docs

---
 README-zh.md              | 35 +++++++++++++++++++++++++++++------
 README.md                 | 37 ++++++++++++++++++++++++++++++-------
 lightrag/api/README-zh.md | 26 +++++++++++++++++---------
 lightrag/api/README.md    | 20 ++++++++++++++------
 4 files changed, 90 insertions(+), 28 deletions(-)

diff --git a/README-zh.md b/README-zh.md
index 148e7907..f4020e1f 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -90,6 +90,11 @@
 
 ## 安装
 
+> **💡 使用 uv 进行包管理**: 本项目使用 [uv](https://docs.astral.sh/uv/) 进行快速可靠的 Python 包管理。
+> 首先安装 uv: `curl -LsSf https://astral.sh/uv/install.sh | sh` (Unix/macOS) 或 `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows)
+>
+> **注意**: 如果您更喜欢使用 pip 也可以，但我们推荐使用 uv 以获得更好的性能和更可靠的依赖管理。
+
 ### 安装LightRAG服务器
 
 LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知识图谱探索和简单的RAG查询界面。LightRAG服务器还提供兼容Ollama的接口，旨在将LightRAG模拟为Ollama聊天模型。这使得AI聊天机器人（如Open WebUI）可以轻松访问LightRAG。
@@ -97,7 +102,11 @@ LightRAG服务器旨在提供Web UI和API支持。Web UI便于文档索引、知
 * 从PyPI安装
 
 ```bash
-pip install "lightrag-hku[api]"
+# 使用 uv (推荐)
+uv pip install "lightrag-hku[api]"
+# 或使用 pip
+# pip install "lightrag-hku[api]"
+
 cp env.example .env
 lightrag-server
 ```
@@ -107,9 +116,17 @@ lightrag-server
 ```bash
 git clone https://github.com/HKUDS/LightRAG.git
 cd LightRAG
-# 如有必要，创建Python虚拟环境
-# 以可开发（编辑）模式安装LightRAG服务器
-pip install -e ".[api]"
+
+# 使用 uv (推荐)
+# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
+uv sync --extra api
+source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
+# Windows 系统: .venv\Scripts\activate
+
+# 或使用 pip 和虚拟环境
+# python -m venv .venv
+# source .venv/bin/activate  # Windows: .venv\Scripts\activate
+# pip install -e ".[api]"
 
 cp env.example .env  # 使用你的LLM和Embedding模型访问参数更新.env文件
 
@@ -140,13 +157,19 @@ docker compose up
 
 ```bash
 cd LightRAG
-pip install -e .
+# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
+uv sync
+source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
+# Windows 系统: .venv\Scripts\activate
+
+# 或: pip install -e .
 ```
 
 * 从PyPI安装
 
 ```bash
-pip install lightrag-hku
+uv pip install lightrag-hku
+# 或: pip install lightrag-hku
 ```
 
 ## 快速开始
diff --git a/README.md b/README.md
index 7a366c05..64921dbc 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,11 @@
 
 ## Installation
 
+> **💡 Using uv for Package Management**: This project uses [uv](https://docs.astral.sh/uv/) for fast and reliable Python package management.
+> Install uv first: `curl -LsSf https://astral.sh/uv/install.sh | sh` (Unix/macOS) or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows)
+>
+> **Note**: You can also use pip if you prefer, but uv is recommended for better performance and more reliable dependency management.
+>
 > **📦 Offline Deployment**: For offline or air-gapped environments, see the [Offline Deployment Guide](./docs/OfflineDeployment.md) for instructions on pre-installing all dependencies and cache files.
 
 ### Install LightRAG Server
@@ -97,7 +102,11 @@ The LightRAG Server is designed to provide Web UI and API support. The Web UI fa
 * Install from PyPI
 
 ```bash
-pip install "lightrag-hku[api]"
+# Using uv (recommended)
+uv pip install "lightrag-hku[api]"
+# Or using pip
+# pip install "lightrag-hku[api]"
+
 cp env.example .env
 lightrag-server
 ```
@@ -107,9 +116,17 @@ lightrag-server
 ```bash
 git clone https://github.com/HKUDS/LightRAG.git
 cd LightRAG
-# Create a Python virtual enviroment if neccesary
-# Install in editable mode with API support
-pip install -e ".[api]"
+
+# Using uv (recommended)
+# Note: uv sync automatically creates a virtual environment in .venv/
+uv sync --extra api
+source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
+# Or on Windows: .venv\Scripts\activate
+
+# Or using pip with virtual environment
+# python -m venv .venv
+# source .venv/bin/activate  # Windows: .venv\Scripts\activate
+# pip install -e ".[api]"
 
 cp env.example .env  # Update the .env with your LLM and embedding configurations
 
@@ -136,17 +153,23 @@ docker compose up
 
 ### Install  LightRAG Core
 
-* Install from source (Recommend)
+* Install from source (Recommended)
 
 ```bash
 cd LightRAG
-pip install -e .
+# Note: uv sync automatically creates a virtual environment in .venv/
+uv sync
+source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
+# Or on Windows: .venv\Scripts\activate
+
+# Or: pip install -e .
 ```
 
 * Install from PyPI
 
 ```bash
-pip install lightrag-hku
+uv pip install lightrag-hku
+# Or: pip install lightrag-hku
 ```
 
 ## Quick Start
diff --git a/lightrag/api/README-zh.md b/lightrag/api/README-zh.md
index 91e4c54d..3b12f265 100644
--- a/lightrag/api/README-zh.md
+++ b/lightrag/api/README-zh.md
@@ -15,26 +15,34 @@ LightRAG 服务器旨在提供 Web 界面和 API 支持。Web 界面便于文档
 * 从 PyPI 安装
 
 ```bash
-pip install "lightrag-hku[api]"
+# 使用 uv (推荐)
+uv pip install "lightrag-hku[api]"
+
+# 或使用 pip
+# pip install "lightrag-hku[api]"
 ```
 
 * 从源代码安装
 
 ```bash
-# Clone the repository
+# 克隆仓库
 git clone https://github.com/HKUDS/lightrag.git
 
-# Change to the repository directory
+# 进入仓库目录
 cd lightrag
 
-# Create a Python virtual environment
-uv venv --seed --python 3.12
-source .venv/bin/activate
+# 使用 uv (推荐)
+# 注意: uv sync 会自动在 .venv/ 目录创建虚拟环境
+uv sync --extra api
+source .venv/bin/activate  # 激活虚拟环境 (Linux/macOS)
+# Windows 系统: .venv\Scripts\activate
 
-# Install in editable mode with API support
-pip install -e ".[api]"
+# 或使用 pip 与虚拟环境
+# python -m venv .venv
+# source .venv/bin/activate  # Windows: .venv\Scripts\activate
+# pip install -e ".[api]"
 
-# Build front-end artifacts
+# 构建前端代码
 cd lightrag_webui
 bun install --frozen-lockfile
 bun run build
diff --git a/lightrag/api/README.md b/lightrag/api/README.md
index 690d9ac9..9e484f1b 100644
--- a/lightrag/api/README.md
+++ b/lightrag/api/README.md
@@ -15,7 +15,11 @@ The LightRAG Server is designed to provide a Web UI and API support. The Web UI
 * Install from PyPI
 
 ```bash
-pip install "lightrag-hku[api]"
+# Using uv (recommended)
+uv pip install "lightrag-hku[api]"
+
+# Or using pip
+# pip install "lightrag-hku[api]"
 ```
 
 * Installation from Source
@@ -27,12 +31,16 @@ git clone https://github.com/HKUDS/lightrag.git
 # Change to the repository directory
 cd lightrag
 
-# Create a Python virtual environment
-uv venv --seed --python 3.12
-source .venv/bin/activate
+# Using uv (recommended)
+# Note: uv sync automatically creates a virtual environment in .venv/
+uv sync --extra api
+source .venv/bin/activate  # Activate the virtual environment (Linux/macOS)
+# Or on Windows: .venv\Scripts\activate
 
-# Install in editable mode with API support
-pip install -e ".[api]"
+# Or using pip with virtual environment
+# python -m venv .venv
+# source .venv/bin/activate  # Windows: .venv\Scripts\activate
+# pip install -e ".[api]"
 
 # Build front-end artifacts
 cd lightrag_webui