Environment:Infiniflow Ragflow Python Runtime

Knowledge Sources	RAGFlow pyproject.toml
Domains	Infrastructure, Backend
Last Updated	2026-02-12 06:00 GMT

Overview

Python 3.12+ runtime environment with Flask/Quart backend, ONNX Runtime, Elasticsearch client, and 100+ Python dependencies for the RAGFlow backend server and task executor.

Description

This environment provides the core Python runtime for all RAGFlow backend services including the API server, task executor, and data sync workers. It is built on Python 3.12 (with support up to 3.14) and includes database connectors (MySQL, PostgreSQL, OceanBase), vector store clients (Elasticsearch, Infinity, OpenSearch), object storage (MinIO, S3, Azure, GCS), and NLP/ML libraries (ONNX Runtime, OpenCV, NLTK). The runtime validates Python version at startup and downloads required NLTK data packages.

Usage

Use this environment for all backend operations including the RAGFlow API server, document processing task executor, data source sync service, admin server, and MCP server. This is the mandatory prerequisite for every backend Implementation page.

System Requirements

Category	Requirement	Notes
OS	Ubuntu 24.04 LTS (Docker) or any Linux	Docker image uses ubuntu:24.04
Hardware	16GB+ RAM, multi-core CPU	50GB+ disk space recommended
Disk	50GB SSD minimum	For models, NLTK data, and document processing

Dependencies

System Packages

`default-jdk` (for Apache Tika PDF server)
`nginx` = 1.29.5
`libglib2.0-0`, `libglx-mesa0`, `libgl1` (OpenCV dependencies)
`unixodbc-dev` (pyodbc / SQL Server connector)

Python Packages

`python` >= 3.12, < 3.15
`elasticsearch-dsl` == 8.12.0
`opensearch-py` == 2.7.1
`infinity-sdk` == 0.7.0-dev2
`mysql-connector-python` >= 9.0.0, < 10.0.0
`minio` == 7.2.4
`valkey` == 6.0.2 (Redis client)
`onnxruntime-gpu` == 1.23.2 (Linux x86_64) or `onnxruntime` == 1.23.2 (macOS/other)
`opencv-python-headless` == 4.10.0.84
`anthropic` == 0.34.1
`mcp` >= 1.19.0
`flask` >= 3.1.0
`quart` >= 0.20.0
`nltk`
`tiktoken`

Credentials

The following environment variables must be set:

`RAGFLOW_SECRET_KEY`: Flask session secret key (minimum 32 characters). Auto-generated if not set, with a security warning.
`MYSQL_PASSWORD`: MySQL database password (default: "infini_rag_flow" — change for production).
`REDIS_PASSWORD`: Redis/Valkey password (default: "infini_rag_flow" — change for production).
`MINIO_USER` / `MINIO_PASSWORD`: MinIO object storage credentials.
`ELASTIC_PASSWORD`: Elasticsearch password (default: "infini_rag_flow" — change for production).

Quick Install

# Using uv (recommended)
uv sync --python 3.12 --all-extras
uv run download_deps.py
pre-commit install

# Or using pip
pip install -r requirements.txt

Code Evidence

Python version validation from `api/validation.py:21-28`:

def python_version_validation():
    required_python_version = (3, 10)
    if sys.version_info < required_python_version:
        logging.info(
            f"Required Python: >= {required_python_version[0]}.{required_python_version[1]}."
        )
        sys.exit(1)

Secret key generation from `common/settings.py:138-153`:

def _get_or_create_secret_key():
    secret_key = os.environ.get("RAGFLOW_SECRET_KEY")
    if secret_key and len(secret_key) >= 32:
        return secret_key
    new_key = secrets.token_hex(32)
    logging.warning("SECURITY WARNING: Using auto-generated SECRET_KEY.")
    return new_key

NLTK data download from `api/validation.py:37-49`:

def download_nltk_data():
    import nltk
    nltk.download('wordnet', halt_on_error=False, quiet=True)
    nltk.download('punkt_tab', halt_on_error=False, quiet=True)

Common Errors

Error Message	Cause	Solution
`Required Python: >= 3.10. Current Python version: X.Y`	Python version too old	Upgrade to Python 3.12+
`SECURITY WARNING: Using auto-generated SECRET_KEY`	RAGFLOW_SECRET_KEY not set	Set `RAGFLOW_SECRET_KEY` env var (min 32 chars)
`Downloading NLTK data failure`	Network issue during startup	Ensure internet access or pre-download NLTK data to `./nltk_data`
`ImportError: No module named 'onnxruntime'`	Wrong ONNX variant installed	Use `onnxruntime-gpu` on Linux x86_64, `onnxruntime` on macOS

Compatibility Notes

macOS: Uses `onnxruntime` (CPU) instead of `onnxruntime-gpu`. Set `MACOS=1` in environment.
Linux x86_64: Uses `onnxruntime-gpu` for CUDA acceleration when available.
Python 3.15+: Not supported per `pyproject.toml` constraint.
pyproject.toml vs runtime check: The project requires Python 3.12+ but the runtime check allows 3.10+ for backward compatibility.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment