Environment:Langgenius Dify Python Backend Environment

Knowledge Sources	Dify Backend API api/pyproject.toml api/README.md
Domains	Infrastructure, Backend
Last Updated	2026-02-12 08:00 GMT

Overview

Python 3.11/3.12 environment with Flask 3.1, Celery 5.5, Gunicorn 23, and gevent 25.9 for the Dify backend API and async worker processes.

Description

This environment provides the runtime context for the Dify backend API server and Celery task workers. It uses Gunicorn with gevent worker class for high-concurrency HTTP request handling, and Celery with Redis as the message broker for asynchronous task processing (dataset indexing, mail delivery, workflow execution, etc.). The backend follows a Domain-Driven Design architecture using Flask as the web framework, SQLAlchemy as the ORM, and Pydantic for data validation.

Critical: Both the Gunicorn and Celery processes require gevent monkey-patching of gRPC and psycopg2 at startup. Incorrect patching order causes deadlocks. See the Gevent_Monkey_Patching_Order heuristic.

Usage

Use this environment for running the Dify backend in any mode: API server (Gunicorn), Worker (Celery), Beat (Celery scheduler), or Migration (database schema updates). It is required by all backend Implementation pages including Docker Compose deployment, application factory, and env sync operations.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu recommended)	Alpine Linux used in Docker images
Hardware	CPU: 1+ cores	Gevent handles concurrency via coroutines, not threads
Disk	2GB+ for dependencies	Additional for app storage volumes
Encoding	UTF-8 (`C.UTF-8` locale)	Set via `LANG=C.UTF-8`, `PYTHONIOENCODING=utf-8`

Dependencies

System Packages

`python` >= 3.11, < 3.13
`uv` (Python package manager, replaces poetry as of v1.3.0)
`libpq-dev` (PostgreSQL client library for psycopg2)
`build-essential` (C compiler for native extensions)

Python Packages (Core)

`flask` ~= 3.1.2
`flask-sqlalchemy` ~= 3.1.1
`flask-migrate` ~= 4.0.7
`flask-login` ~= 0.6.3
`flask-cors` ~= 6.0.0
`flask-compress` >= 1.17, < 1.18
`gunicorn` ~= 23.0.0
`gevent` ~= 25.9.1
`celery` ~= 5.5.2
`redis[hiredis]` ~= 6.1.0
`sqlalchemy` ~= 2.0.29
`pydantic` ~= 2.11.4

Python Packages (ML/NLP)

`transformers` ~= 4.56.1
`tiktoken` ~= 0.9.0
`numpy` ~= 1.26.4
`pandas` ~= 2.2.2
`litellm` == 1.77.1 (pinned to avoid madoka dependency issue)

Python Packages (Observability)

`opentelemetry-api` == 1.27.0
`opentelemetry-distro` == 0.48b0
`opentelemetry-exporter-otlp` == 1.27.0
`langfuse` ~= 2.51.3
`langsmith` ~= 0.1.77

Python Packages (Gevent Compatibility)

`psycogreen` ~= 1.0.2 (patches psycopg2 for gevent)
`grpcio` (patched via `grpc.experimental.gevent`)

Credentials

The following environment variables must be set:

`SECRET_KEY`: Application secret key for signing. Generate with `openssl rand -base64 42`.
`DB_USERNAME` / `DB_PASSWORD`: Database credentials for PostgreSQL or MySQL.
`REDIS_PASSWORD`: Redis authentication password (default: `difyai123456`).
`CELERY_BROKER_URL`: Redis URL for Celery broker (default: `redis://:difyai123456@redis:6379/1`).
`CODE_EXECUTION_API_KEY`: API key for the sandbox code execution service (default: `dify-sandbox`).

Optional credentials:

`HF_TOKEN`: HuggingFace API token for model downloads.
`DIFY_ENV_NACOS_USERNAME` / `DIFY_ENV_NACOS_PASSWORD`: Nacos remote config credentials.
`DIFY_ENV_NACOS_ACCESS_KEY` / `DIFY_ENV_NACOS_SECRET_KEY`: Nacos AK/SK authentication.

Quick Install

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all backend dependencies
cd api
uv sync

# Run the API server
uv run --project api flask run --host 0.0.0.0 --port 5001

# Run the Celery worker
uv run --project api celery -A app.celery worker -Q dataset,mail,ops_trace

Code Evidence

Python version constraint from `api/pyproject.toml:4`:

requires-python = ">=3.11,<3.13"

LiteLLM pinned due to dependency conflict from `api/pyproject.toml:43`:

"litellm==1.77.1",                                  # Pinned to avoid madoka dependency issue

UTF-8 encoding enforcement from `api/docker/entrypoint.sh:5-9`:

# Set UTF-8 encoding to address potential encoding issues in containerized environments
# Use C.UTF-8 which is universally available in all containers
export LANG=${LANG:-C.UTF-8}
export LC_ALL=${LC_ALL:-C.UTF-8}
export PYTHONIOENCODING=${PYTHONIOENCODING:-utf-8}

Gevent monkey-patching in Gunicorn from `api/gunicorn.conf.py:30-42`:

def post_patch(event):
    if not isinstance(event, gevent_events.GeventDidPatchBuiltinModulesEvent):
        return
    grpc_gevent.init_gevent()
    print("gRPC patched with gevent.", flush=True)
    pscycogreen_gevent.patch_psycopg()
    print("psycopg2 patched with gevent.", flush=True)

Common Errors

Error Message	Cause	Solution
`ModuleNotFoundError: No module named 'gevent'`	Python environment not properly set up	Run `uv sync` in the `api/` directory
Deadlock on Gunicorn startup	gRPC patched before gevent monkey-patches stdlib	Ensure `post_patch` uses `GeventDidPatchBuiltinModulesEvent`, not `post_fork`
`DetachedInstanceError` on SQLAlchemy model access	Session closed before accessing lazy-loaded attributes	Use `expire_on_commit=False` or reload object in new session
`CELERY_BROKER_URL` connection refused	Redis not running or wrong URL	Verify Redis is running on port 6379 and broker URL matches

Compatibility Notes

Windows: Gevent worker class is not recommended. Use `SERVER_WORKER_CLASS=sync` or `SERVER_WORKER_CLASS=solo` instead. Set `CELERY_WORKER_CLASS` accordingly.
macOS: Full support with gevent. Ensure `libpq` is installed via Homebrew for psycopg2.
Database: Supports PostgreSQL (default, port 5432), MySQL (port 3306), OceanBase, and SeekDB. PostgreSQL recommended for vector search with pgvector extension.
Python 3.13+: Not yet supported. Constrained to `<3.13` in pyproject.toml.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment