Migrate Dockerfile from pip to uv package manager for faster builds

• Replace pip with uv for dependencies
• Add offline extras to Dockerfile.offline
• Update UV_LOCK_GUIDE.md with new commands
• Improve build caching and performance

Dockerfile

@@ -6,73 +6,78 @@ WORKDIR /app
 # Copy frontend source code
 COPY lightrag_webui/ ./lightrag_webui/
 
-# Build frontend
+# Build frontend assets for inclusion in the API package
-RUN cd lightrag_webui && \
+RUN cd lightrag_webui \
-    bun install --frozen-lockfile && \
+    && bun install --frozen-lockfile \
-    bun run build
+    && bun run build
 
-# Python build stage
+# Python build stage - using uv for package installation
-FROM python:3.12-slim AS builder
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV UV_SYSTEM_PYTHON=1
+ENV UV_COMPILE_BYTECODE=1
 
 WORKDIR /app
 
-# Upgrade pip、setuptools and wheel to the latest version
+# Install system dependencies required by some wheels
-RUN pip install --upgrade pip setuptools wheel
+RUN apt-get update \
-
+    && apt-get install -y --no-install-recommends \
-# Install Rust and required build dependencies
+        curl \
-RUN apt-get update && apt-get install -y \
+        build-essential \
-    curl \
+        pkg-config \
-    build-essential \
-    pkg-config \
     && rm -rf /var/lib/apt/lists/* \
-    && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
+    && curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-    && . $HOME/.cargo/env
 
-# Copy pyproject.toml and source code for dependency installation
+ENV PATH="/root/.cargo/bin:/root/.local/bin:${PATH}"
+
+# Ensure shared data directory exists for uv caches
+RUN mkdir -p /root/.local/share/uv
+
+# Copy project metadata and sources
 COPY pyproject.toml .
 COPY setup.py .
+COPY uv.lock .
 COPY lightrag/ ./lightrag/
 
-# Copy frontend build output from frontend-builder stage
+# Include pre-built frontend assets from the previous stage
 COPY --from=frontend-builder /app/lightrag/api/webui ./lightrag/api/webui
 
-# Install dependencies
+# Install project dependencies (base + API extras)
-ENV PATH="/root/.cargo/bin:${PATH}"
+RUN uv sync --frozen --no-dev --extra api
-RUN pip install --user --no-cache-dir --use-pep517 .
-RUN pip install --user --no-cache-dir --use-pep517 .[api]
-
-# Install depndencies for default storage
-RUN pip install --user --no-cache-dir nano-vectordb networkx
-# Install depndencies for default LLM
-RUN pip install --user --no-cache-dir openai ollama tiktoken
-# Install depndencies for default document loader
-RUN pip install --user --no-cache-dir pypdf2 python-docx python-pptx openpyxl
 
 # Final stage
 FROM python:3.12-slim
 
 WORKDIR /app
 
-# Upgrade pip and setuptools
+# Install uv for package management
-RUN pip install --upgrade pip setuptools wheel
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 
-# Copy only necessary files from builder
+ENV UV_SYSTEM_PYTHON=1
+
+# Copy installed packages and application code
 COPY --from=builder /root/.local /root/.local
+COPY --from=builder /app/.venv /app/.venv
 COPY --from=builder /app/lightrag ./lightrag
+COPY pyproject.toml .
 COPY setup.py .
+COPY uv.lock .
 
-RUN pip install --use-pep517 ".[api]"
+# Ensure the installed scripts are on PATH
-# Make sure scripts in .local are usable
+ENV PATH=/app/.venv/bin:/root/.local/bin:$PATH
-ENV PATH=/root/.local/bin:$PATH
 
-# Create necessary directories
+# Sync dependencies inside the final image using uv
+RUN uv sync --frozen --no-dev --extra api
+
+# Create persistent data directories
 RUN mkdir -p /app/data/rag_storage /app/data/inputs
 
 # Docker data directories
 ENV WORKING_DIR=/app/data/rag_storage
 ENV INPUT_DIR=/app/data/inputs
 
-# Expose the default port
+# Expose API port
 EXPOSE 9621
 
 # Set entrypoint

Dockerfile.offline

@@ -43,8 +43,8 @@ COPY lightrag/ ./lightrag/
 # Include pre-built frontend assets from the previous stage
 COPY --from=frontend-builder /app/lightrag/api/webui ./lightrag/api/webui
 
-# Install base and API extras so CLI helpers work during build
+# Install base, API, and offline extras so CLI helpers work during build
-RUN uv sync --frozen --no-dev --extra api
+RUN uv sync --frozen --no-dev --extra api --extra offline
 
 # Prepare offline cache directory and pre-populate tiktoken data
 # Use uv run to execute commands from the virtual environment
@@ -75,7 +75,7 @@ ENV PATH=/app/.venv/bin:/root/.local/bin:$PATH
 
 # Install dependencies with uv sync (uses locked versions from uv.lock)
 # IMPORTANT: Must be done BEFORE creating data/ directory to avoid setuptools error
-RUN uv sync --frozen --no-dev --extra api
+RUN uv sync --frozen --no-dev --extra api --extra offline
 
 # Create persistent data directories AFTER package installation
 RUN mkdir -p /app/data/rag_storage /app/data/inputs /app/data/tiktoken

docs/UV_LOCK_GUIDE.md

@@ -110,6 +110,16 @@ RUN uv sync --frozen --no-dev --extra api
 `--frozen` guarantees reproducible builds because uv will refuse to deviate from the locked versions.
 `--extra api` install API server
 
+## Generating a lock file that includes offline dependencies
+
+If you need `uv.lock` to capture the optional offline stacks, regenerate it with the relevant extras enabled:
+
+```bash
+uv lock --extra api --extra offline
+```
+
+This command resolves the base project requirements plus both the `api` and `offline` optional dependency sets, ensuring downstream `uv sync --frozen --extra api --extra offline` installs work without further resolution.
+
 ## Frequently asked questions
 
 - **`uv.lock` is almost 1 MB. Does that matter?**