diff --git a/docs/features/extensibility/plugin/tools/development.mdx b/docs/features/extensibility/plugin/tools/development.mdx index 68ca44cc..44f307b9 100644 --- a/docs/features/extensibility/plugin/tools/development.mdx +++ b/docs/features/extensibility/plugin/tools/development.mdx @@ -1521,7 +1521,7 @@ We strongly recommend using an [OpenAPI tool server](/features/extensibility/plu **Do not rely on runtime pip installation in production environments.** When running with `UVICORN_WORKERS > 1` or multiple replicas, each worker/replica attempts to install packages independently on startup. This causes **race conditions** where concurrent pip processes crash with `AssertionError` because pip's internal locking detects the simultaneous installs. -**The recommended approach for production is to pre-install all required packages at image build time** using a custom Dockerfile: +**Set [`ENABLE_AUTO_DEPENDENCY_INSTALL=False`](/reference/env-configuration#enable_auto_dependency_install) in production** to disable runtime pip installs entirely. Then pre-install all required packages at image build time using a custom Dockerfile: ```dockerfile FROM ghcr.io/open-webui/open-webui:main diff --git a/docs/reference/env-configuration.mdx b/docs/reference/env-configuration.mdx index 69c97475..9a1dcc51 100644 --- a/docs/reference/env-configuration.mdx +++ b/docs/reference/env-configuration.mdx @@ -6366,6 +6366,32 @@ bypassed when accessing documents from MIT. Open WebUI provides environment variables to customize the pip installation process. Below are the environment variables used by Open WebUI for adjusting package installation behavior: +#### `ENABLE_AUTO_DEPENDENCY_INSTALL` + +- Type: `bool` +- Default: `True` +- Description: Controls whether Open WebUI automatically runs `pip install` for Python packages declared in function and tool `requirements` frontmatter. When enabled, dependencies are installed at runtime — both on startup (for all active functions and admin tools) and when saving a function or tool with new requirements. + +:::warning Security Hardening for Production + +**Strongly recommended: set `ENABLE_AUTO_DEPENDENCY_INSTALL=False` in production.** Runtime pip installs allow any admin-uploaded function or tool to install arbitrary Python packages into the running process. Disabling this: + +- **Prevents arbitrary package installation** from user-uploaded code +- **Eliminates race conditions** that crash workers when `UVICORN_WORKERS > 1` or multiple replicas attempt concurrent pip installs +- **Ensures reproducible deployments** — all dependencies are baked into the container image + +Pre-install required packages in your Dockerfile instead: + +```dockerfile +FROM ghcr.io/open-webui/open-webui:main + +RUN pip install --no-cache-dir python-docx requests beautifulsoup4 +``` + +When disabled, functions and tools that import missing packages will fail with a `ModuleNotFoundError` at load time, clearly indicating which packages need to be pre-installed. + +::: + #### `PIP_OPTIONS` - Type: `str` diff --git a/docs/troubleshooting/multi-replica.mdx b/docs/troubleshooting/multi-replica.mdx index 7355a1d9..457b25f2 100644 --- a/docs/troubleshooting/multi-replica.mdx +++ b/docs/troubleshooting/multi-replica.mdx @@ -226,7 +226,7 @@ See [DATABASE_POOL_SIZE](/reference/env-configuration#database_pool_size) for de When a function or tool specifies `requirements` in its frontmatter, Open WebUI runs `pip install` at runtime. With multiple workers or replicas, each process attempts the installation independently, causing pip's internal lock to detect the conflict and crash. **Solution:** -**Do not rely on runtime pip installation in production.** Pre-install all required packages at image build time: +**Set [`ENABLE_AUTO_DEPENDENCY_INSTALL=False`](/reference/env-configuration#enable_auto_dependency_install)** to disable runtime pip installs entirely. Then pre-install all required packages at image build time: ```dockerfile FROM ghcr.io/open-webui/open-webui:main