Python Dependency Management#

RAGFlow manages Python dependencies through two pyproject.toml files — one for the main application and one for the DeepDoc server. The main pyproject.toml at the repo root is the authoritative source for the primary app, SDK, and sandbox. Install tooling is uv; the lockfile is uv.lock.

Python Version Constraints#

The DeepDoc server deliberately excludes Python 3.13, which is why its Dockerfile installs Python 3.12 from apt rather than using uv. 3

Main Dependency List#

The main project's dependencies block is a flat list in [project.dependencies] covering ~130 packages. Key conventions used throughout:

• Exact pins for packages with known regression histories (e.g., "litellm==1.84.0" — comment explains it was previously pinned to 1.82.5 due to broken imports in subsequent minor bumps). 4
• Bounded ranges (e.g., "aiosmtplib>=5.1.1,<6.0.0") for packages where major-version breaks are expected.
• URL/VCS references for forks not on PyPI, e.g., graspologic is pulled from a Gitee mirror commit. 5
• Wheel URLs for large model assets, e.g., spaCy's en_core_web_sm is fetched directly as a GitHub release wheel. 6

There is also a block of commented-out packages (lines 140–171) that are transitive dependencies already pulled in; they are kept commented for documentation purposes. 7

Platform-Specific Variants: onnxruntime vs onnxruntime-gpu#

The most prominent use of PEP 508 environment markers is ONNX Runtime selection 8:

"onnxruntime==1.23.2; sys_platform == 'darwin' or platform_machine != 'x86_64'",
"onnxruntime-gpu==1.23.2; sys_platform != 'darwin' and platform_machine == 'x86_64'",

• onnxruntime (CPU-only): installed on macOS or any non-x86_64 architecture (e.g., ARM).
• onnxruntime-gpu (CUDA-enabled): installed on Linux/Windows x86_64.

This means the GPU-capable build is selected automatically on typical x86_64 Linux servers without any manual flag or extra step. The DeepDoc server's own pyproject.toml unconditionally uses onnxruntime because it targets Python 3.11/3.12 where GPU selection is handled externally. 9

uv-Specific Sections#

Beyond the standard PEP 517 fields, RAGFlow uses three [tool.uv] keys to enforce security constraints on the entire resolved graph:

constraint-dependencies#

Lines 207–249 list packages where minimum versions are required globally to address CVEs in transitive dependencies — packages RAGFlow does not directly import but which are pulled in by its deps. Examples:

• pyasn1>=0.6.4 — CVE-2026-30922, pulled in via google-auth / rsa / pyasn1-modules
• urllib3>=2.7.0 — CVE-2026-44431/CVE-2026-44432, pulled in via requests, minio, etc.
• lxml>=6.1.1 — CVE-2026-41066, pulled in via html-text, readability-lxml, crawl4ai

Each entry has an inline comment explaining the CVE(s) and the transitive pull chain.

exclude-dependencies#

Lines 250–256 prevent two packages from being installed at all:

• unclecode-litellm — installed by crawl4ai>=0.8.6; it occupies the same litellm namespace and would corrupt imports.
• agentrun-mem0ai — transitive dep of agentrun-sdk; not used anywhere in RAGFlow.

override-dependencies#

Lines 257–261 force a floor on a package that a direct dependency over-constrains. moodlepy<=0.24.1 pins attrs<23.0.0, but trio>=0.26.0 requires attrs>=23.2.0; the override lets both coexist since attrs 23.x is backward-compatible.

Index Configuration#

The default index is the Aliyun PyPI mirror for CI speed. PyPI is registered as an explicit secondary index, used only for packages listed under [tool.uv.sources] 10:

[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
explicit = true

[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple"

[tool.uv.sources]
trio = [{ index = "pypi" }]

trio is pinned to PyPI because trio>=0.26.0 (Python 3.13-compatible) had not yet propagated to the Aliyun mirror at the time of pinning. 11

Dependency Groups (Dev/Test)#

The [dependency-groups] section 12 holds a test group with pytest, hypothesis, playwright, and document-format libraries needed only for test runs. These are not installed in production images. Install with:

uv sync --group test

DeepDoc Server Dependencies#

The deepdoc-server-oss sub-project has a minimal, inference-focused dependency set: litserve, onnxruntime, opencv-python-headless, numpy, pillow, pyclipper, python-multipart, shapely, and six. 9 It uses Hatchling as its build backend 13, unlike the main project which uses setuptools with an explicit packages list.