Environment Variable Configuration

Overview

Open WebUI provides a large range of environment variables that allow you to customize and configure various aspects of the application. This page serves as a comprehensive reference for all available environment variables, providing their types, default values, and descriptions. As new variables are introduced, this page will be updated to reflect the growing configuration options.

info

This page is up-to-date with Open WebUI release version v0.8.5, but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions.

Important Note on `PersistentConfig` Environment Variables

note

When launching Open WebUI for the first time, all environment variables are treated equally and can be used to configure the application. However, for environment variables marked as PersistentConfig, their values are persisted and stored internally.

After the initial launch, if you restart the container, PersistentConfig environment variables will no longer use the external environment variable values. Instead, they will use the internally stored values.

In contrast, regular environment variables will continue to be updated and applied on each subsequent restart.

You can update the values of PersistentConfig environment variables directly from within Open WebUI, and these changes will be stored internally. This allows you to manage these configuration settings independently of the external environment variables.

Please note that PersistentConfig environment variables are clearly marked as such in the documentation below, so you can be aware of how they will behave.

To disable this behavior and force Open WebUI to always use your environment variables (ignoring the database), set ENABLE_PERSISTENT_CONFIG to False.

CRITICAL WARNING: When ENABLE_PERSISTENT_CONFIG is False, you may still be able to edit settings in the Admin UI. However, these changes are NOT saved permanently. They will persist only for the current session and will be lost when you restart the container, as the system will revert to the values defined in your environment variables.

Troubleshooting Ignored Environment Variables 🛠️

If you change an environment variable (like ENABLE_SIGNUP=True) but don't see the change reflected in the UI (e.g., the "Sign Up" button is still missing), it's likely because a value has already been persisted in the database from a previous run or a persistent Docker volume.

Option 1: Using `ENABLE_PERSISTENT_CONFIG` (Temporary Fix)

Set ENABLE_PERSISTENT_CONFIG=False in your environment. This forces Open WebUI to read your variables directly. Note that UI-based settings changes will not persist across restarts in this mode.

Option 2: Update via Admin UI (Recommended)

The simplest and safest way to change PersistentConfig settings is directly through the Admin Panel within Open WebUI. Even if an environment variable is set, changes made in the UI will take precedence and be saved to the database.

Option 3: Manual Database Update (Last Resort / Lock-out Recovery)

If you are locked out or cannot access the UI, you can manually update the SQLite database via Docker:

docker exec -it open-webui sqlite3 /app/backend/data/webui.db "UPDATE config SET data = json_set(data, '$.ENABLE_SIGNUP', json('true'));"

(Replace ENABLE_SIGNUP and true with the specific setting and value needed.)

Option 4: Resetting for a Fresh Install

If you are performing a clean installation and want to ensure all environment variables are fresh:

Stop the container.
Remove the persistent volume: docker volume rm open-webui.
Restart the container.

danger

Warning: Removing the volume will delete all user data, including chats and accounts.

App/Backend

The following environment variables are used by backend/open_webui/config.py to provide Open WebUI startup configuration. Please note that some variables may have different default values depending on whether you're running Open WebUI directly or via Docker. For more information on logging environment variables, see our logging documentation.

General

`WEBUI_URL`

Type: str
Default: http://localhost:3000
Description: Specifies the URL where your Open WebUI installation is reachable. Needed for search engine support and OAuth/SSO.
Persistence: This environment variable is a PersistentConfig variable.

warning

This variable has to be set before you start using OAuth/SSO for authentication. Since this is a persistent config environment variable, you can only change it through one of the following options:

Temporarily disabling persistent config using ENABLE_PERSISTENT_CONFIG
Changing WEBUI_URL in the admin panel > settings and changing "WebUI URL".

Failure to set WEBUI_URL before using OAuth/SSO will result in failure to log in.

`ENABLE_SIGNUP`

Type: bool
Default: True
Description: Toggles user account creation.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_SIGNUP_PASSWORD_CONFIRMATION`

Type: bool
Default: False
Description: If set to True, a "Confirm Password" field is added to the sign-up page to help users avoid typos when creating their password.

`WEBUI_ADMIN_EMAIL`

Type: str
Default: Empty string (' ')
Description: Specifies the email address for an admin account to be created automatically on first startup when no users exist. This enables headless/automated deployments without manual account creation. When combined with WEBUI_ADMIN_PASSWORD, the admin account is created during application startup, and ENABLE_SIGNUP is automatically disabled to prevent unauthorized account creation.

info

This variable is designed for automated/containerized deployments where manual admin account creation is impractical. The admin account is only created if:

No users exist in the database (fresh installation)
Both WEBUI_ADMIN_EMAIL and WEBUI_ADMIN_PASSWORD are configured

After the admin account is created, sign-up is automatically disabled for security. You can re-enable it later via the Admin Panel if needed.

`WEBUI_ADMIN_PASSWORD`

Type: str
Default: Empty string (' ')
Description: Specifies the password for the admin account to be created automatically on first startup when no users exist. Must be used in conjunction with WEBUI_ADMIN_EMAIL. The password is securely hashed before storage using the same mechanism as manual account creation.

danger

Security Considerations

Use a strong, unique password for production deployments
Consider using secrets management (Docker secrets, Kubernetes secrets, environment variable injection) rather than storing the password in plain text configuration files
After initial setup, change the admin password through the UI for enhanced security
Never commit this value to version control

`WEBUI_ADMIN_NAME`

Type: str
Default: Admin
Description: Specifies the display name for the automatically created admin account. This is used when WEBUI_ADMIN_EMAIL and WEBUI_ADMIN_PASSWORD are configured for headless admin creation.

`ENABLE_LOGIN_FORM`

Type: bool
Default: True
Description: Toggles email, password, sign-in and "or" (only when ENABLE_OAUTH_SIGNUP is set to True) elements.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_PASSWORD_AUTH`

Type: bool
Default: True
Description: Allows both password and SSO authentication methods to coexist when set to True. When set to False, it disables all password-based login attempts on the /signin and /ldap endpoints, enforcing strict SSO-only authentication. Disable this setting in production environments with fully configured SSO to prevent credential-based account takeover attacks; keep it enabled if you require password authentication as a backup or have not yet completed SSO configuration. Should never be disabled if OAUTH/SSO is not being used.

tip

This SHOULD be set to False if you only use SSO/OAUTH for Login and expose your Open WebUI publicly as to prevent password based logins.

danger

This should only ever be set to False when ENABLE_OAUTH_SIGNUP is also being used and set to True. Never disable this if OAUTH/SSO is not being used. Failure to do so will result in the inability to login.

`DEFAULT_LOCALE`

Type: str
Default: en
Description: Sets the default locale for the application.
Persistence: This environment variable is a PersistentConfig variable.

`DEFAULT_MODELS`

Type: str
Default: Empty string (' '), since None.
Description: Sets a default Language Model.
Persistence: This environment variable is a PersistentConfig variable.

`DEFAULT_PINNED_MODELS`

Type: str
Default: Empty string (' ')
Description: Comma-separated list of model IDs to pin by default for new users who haven't customized their pinned models. This provides a pre-selected set of frequently used models in the model selector for new accounts.
Example: gpt-4,claude-3-opus,llama-3-70b
Persistence: This environment variable is a PersistentConfig variable.

`DEFAULT_MODEL_METADATA`

Type: dict (JSON object)
Default: {}
Description: Sets global default metadata (capabilities and other model info) for all models. These defaults act as a baseline — per-model overrides always take precedence. For capabilities, the defaults and per-model values are merged (per-model wins on conflicts). For other metadata fields, the default is only applied if the model has no value set. Configurable via Admin Settings → Models.
Persistence: This environment variable is a PersistentConfig variable. Stored at config key models.default_metadata.

`DEFAULT_MODEL_PARAMS`

Type: dict (JSON object)
Default: {}
Description: Sets global default parameters (temperature, top_p, max_tokens, seed, etc.) for all models. These defaults are applied as a baseline at chat completion time — per-model parameter overrides always take precedence. Configurable via Admin Settings → Models.
Persistence: This environment variable is a PersistentConfig variable. Stored at config key models.default_params.

`DEFAULT_USER_ROLE`

Type: str
Options:
- pending - New users are pending until their accounts are manually activated by an admin.
- user - New users are automatically activated with regular user permissions.
- admin - New users are automatically activated with administrator permissions.
Default: pending
Description: Sets the default role assigned to new users.
Persistence: This environment variable is a PersistentConfig variable.

`DEFAULT_GROUP_ID`

Type: str
Default: Empty string (' ')
Description: Sets the default group ID to assign to new users upon registration.
Persistence: This environment variable is a PersistentConfig variable.

`DEFAULT_GROUP_SHARE_PERMISSION`

Type: str
Options: members, true, false
Default: members
Description: Controls the default "Who can share to this group" setting for newly created groups. members means only group members can share to the group, true means anyone can share, and false means no one can share to the group. This applies both to groups created manually and groups created automatically (e.g. via SCIM or OAuth group sync). Existing groups are not affected — this only sets the initial default for new groups.

`PENDING_USER_OVERLAY_TITLE`

Type: str
Default: Empty string (' ')
Description: Sets a custom title for the pending user overlay.
Persistence: This environment variable is a PersistentConfig variable.

`PENDING_USER_OVERLAY_CONTENT`

Type: str
Default: Empty string (' ')
Description: Sets a custom text content for the pending user overlay.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_CHANNELS`

Type: bool
Default: False
Description: Enables or disables channel support.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_FOLDERS`

Type: bool
Default: True
Description: Enables or disables the folders feature, allowing users to organize their chats into folders in the sidebar.
Persistence: This environment variable is a PersistentConfig variable.

`FOLDER_MAX_FILE_COUNT`

Type: int
Default: ("") empty string
Description: Sets the maximum number of files processing allowed per folder.
Persistence: This environment variable is a PersistentConfig variable. It can be configured in the Admin Panel > Settings > General > Folder Max File Count. Default is none (empty string) which is unlimited.

`ENABLE_NOTES`

Type: bool
Default: True
Description: Enables or disables the notes feature, allowing users to create and manage personal notes within Open WebUI.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_MEMORIES`

Type: bool
Default: True
Description: Enables or disables the memory feature, allowing models to store and retrieve long-term information about users.
Persistence: This environment variable is a PersistentConfig variable.

`WEBHOOK_URL`

Type: str
Description: Sets a webhook for integration with Discord/Slack/Microsoft Teams.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_ADMIN_EXPORT`

Type: bool
Default: True
Description: Controls whether admins can export data, chats and the database in the admin panel. Database exports only work for SQLite databases for now.

`ENABLE_ADMIN_CHAT_ACCESS`

Type: bool
Default: True
Description: Enables admin users to directly access the chats of other users. When disabled, admins can no longer accesss user's chats in the admin panel. If you disable this, consider disabling ENABLE_ADMIN_EXPORT too, if you are using SQLite, as the exports also contain user chats.

`ENABLE_ADMIN_ANALYTICS`

Type: bool
Default: True
Description: Controls whether the Analytics tab is visible and accessible in the admin panel. When set to False, the analytics API router is not mounted and the tab is hidden from the admin navigation. Useful for deployments where analytics data collection or display is not desired. Requires a restart to take effect.

`BYPASS_ADMIN_ACCESS_CONTROL`

Type: bool
Default: True
Description: When disabled, admin users are treated like regular users for workspace access (models, knowledge, prompts, tools, and notes) and only see items they have explicit permission to access through the existing access control system. This also applies to the visibility of models in the model selector - admins will be treated as regular users: base models and custom models they do not have explicit permission to access, will be hidden. If set to True (Default), admins have access to all created items in the workspace area (including other users' notes) and all models in the model selector, regardless of access permissions. This environment variable deprecates ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS. If you are still using ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS you should switch to BYPASS_ADMIN_ACCESS_CONTROL.

`ENABLE_USER_WEBHOOKS`

Type: bool
Default: False
Description: Enables or disables user webhooks.
Persistence: This environment variable is a PersistentConfig variable.

`RESPONSE_WATERMARK`

Type: str
Default: Empty string (' ')
Description: Sets a custom text that will be included when you copy a message in the chat. e.g., "This text is AI generated" -> will add "This text is AI generated" to every message, when copied.
Persistence: This environment variable is a PersistentConfig variable.

`THREAD_POOL_SIZE`

Type: int
Default: 0
Description: Sets the thread pool size for FastAPI/AnyIO blocking calls. By default (when set to 0) FastAPI/AnyIO use 40 threads. In case of large instances and many concurrent users, it may be needed to increase THREAD_POOL_SIZE to prevent blocking.

info

If you are running larger instances, you WILL NEED to set this to a higher value like multiple hundreds if not thousands (e.g. 1000) otherwise your app may get stuck the default pool size (which is 40 threads) is full and will not react anymore.

`ENABLE_CUSTOM_MODEL_FALLBACK`

Type: bool
Default: False
Description: Controls whether custom models should fall back to a default model if their assigned base model is missing. When set to True, if a custom model's base model is not found, the system will use the first model from the configured DEFAULT_MODELS list instead of returning an error.

`SHOW_ADMIN_DETAILS`

Type: bool
Default: True
Description: Toggles whether to show admin user details in the interface.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_PUBLIC_ACTIVE_USERS_COUNT`

Type: bool
Default: True
Description: Controls whether the active user count is visible to all users or restricted to administrators only. When set to False, only admin users can see how many users are currently active, reducing backend load and addressing privacy concerns in large deployments.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_USER_STATUS`

Type: bool
Default: True
Description: Globally enables or disables user status functionality. When disabled, the status UI (including blinking active/away indicators and status messages) is hidden across the application, and user status API endpoints are restricted.
Persistence: This environment variable is a PersistentConfig variable. It can be toggled in the Admin Panel > Settings > General > User Status.

`ENABLE_EASTER_EGGS`

Type: bool
Default: True
Description: Enables or disables easter egg features in the UI, such as special themes (e.g., the "Her" theme option in the theme selector). Set to False to hide these optional novelty features from users.

`ADMIN_EMAIL`

Type: str
Description: Sets the admin email shown by SHOW_ADMIN_DETAILS
Persistence: This environment variable is a PersistentConfig variable.

`ENV`

Type: str
Options:
- dev - Enables the FastAPI API documentation on /docs
- prod - Automatically configures several environment variables
Default:
- Backend Default: dev
- Docker Default: prod
Description: Environment setting.

`ENABLE_PERSISTENT_CONFIG`

Type: bool
Default: True
Description: Controls whether the system prioritizes configuration saved in the database over environment variables.
- True (Default): Values saved in the database (via the Admin UI) take precedence. If a value is set in the UI, the environment variable is ignored for that setting.
- False: Environment variables take precedence. The system will not load configuration from the database at startup if an environment variable is present (or it will use the default).
  - CRITICAL WARNING: When set to False, you can still seemingly "change" settings in the Admin UI. These changes will apply to the current running session but will be lost upon restart. The system will revert to the values defined in your environment variables (or defaults) every time it boots up.
  - Use Case: Set this to False if you want to strictly manage configuration via a docker-compose.yaml or .env file and prevent UI changes from persisting across restarts.

`CUSTOM_NAME`

Type: str
Description: Sets WEBUI_NAME but polls api.openwebui.com for metadata.

`WEBUI_NAME`

Type: str
Default: Open WebUI
Description: Sets the main WebUI name. Appends (Open WebUI) if overridden.

`PORT`

Type: int
Default: 8080
Description: Sets the port to run Open WebUI from.

info

If you're running the application via Python and using the open-webui serve command, you cannot set the port using the PORT configuration. Instead, you must specify it directly as a command-line argument using the --port flag. For example:

open-webui serve --port 9999

This will run the Open WebUI on port 9999. The PORT environment variable is disregarded in this mode.

`ENABLE_REALTIME_CHAT_SAVE`

Type: bool
Default: False
Description: When enabled, the system saves each individual chunk of streamed chat data to the database in real time.

EXTREME PERFORMANCE RISK: DO NOT ENABLE IN PRODUCTION

It is strongly recommended to NEVER enable this setting in production or multi-user environments.

Enabling ENABLE_REALTIME_CHAT_SAVE causes every single token generated by the LLM to trigger a separate database write operation. In a multi-user environment, this will:

Exhaust Database Connection Pools: Rapid-fire writes will quickly consume all available database connections, leading to "QueuePool limit reached" errors and application-wide freezes.
Severe Performance Impact: The overhead of thousands of database transactions per minute will cause massive latency for all users.
Hardware Strain: It creates immense I/O pressure on your storage system.

Keep this set to False (the default). Chats are still saved automatically once generation is complete. This setting is only intended for extreme debugging scenarios or single-user environments where sub-second persistence of every token is more important than stability.

`ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION`

Type: bool
Default: False
Description: When set to true, it automatically uploads base64-encoded images exceeding 1KB in markdown and converts them into image file URLs to reduce the size of response text. Some multimodal models directly output images as Base64 strings within the Markdown content. This results in larger response bodies, placing strain on CPU, network, Redis, and database resources.

`CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE`

Type: int
Default: 1
Description: Sets a system-wide minimum value for the number of tokens to batch together before sending them to the client during a streaming response. This allows an administrator to enforce a baseline level of performance and stability across the entire system by preventing excessively small chunk sizes that can cause high CPU load. The final chunk size used for a response will be the highest value set among this global variable, the model's advanced parameters, or the per-chat settings. The default is 1, which applies no minimum batching at the global level.

`CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE`

Type: int
Default: Empty string (' '), which disables the limit (equivalent to None)
Description: Sets the maximum buffer size in bytes for handling stream response chunks. When a single chunk exceeds this limit, the system returns an empty JSON object and skips subsequent oversized data until encountering normally-sized chunks. This prevents memory issues when dealing with extremely large responses from certain providers (e.g., models like gemini-2.5-flash-image or services returning extensive web search data exceeding). Set to an empty string or a negative value to disable chunk size limitations entirely. Recommended values are 16-20 MB (16777216) or larger depending on the image size of the image generation model (4K images may need even more).

info

It is recommended to set this to a high single-digit or low double-digit value if you run Open WebUI with high concurrency, many users, and very fast streaming models.

`ENABLE_RESPONSES_API_STATEFUL`

Type: bool
Default: False
Description: Enables stateful session handling for the Responses API by forwarding previous_response_id to the upstream endpoint. When enabled, Open WebUI anchors each response to the previous one, allowing the upstream provider to maintain conversation state server-side.

Experimental

Only enable this if your upstream Responses API endpoint supports stateful sessions (i.e., server-side response storage with previous_response_id anchoring). Most proxies and third-party endpoints are stateless and will break if this is enabled. This is intended for direct connections to providers like OpenAI that natively support the Responses API with session state.

`BYPASS_MODEL_ACCESS_CONTROL`

Type: bool
Default: False
Description: Bypasses model access control. When set to true, all users (and admins alike) will have access to all models, regardless of the model's privacy setting (Private, Public, Shared with certain groups). This is useful for smaller or individual Open WebUI installations where model access restrictions may not be needed.

`WEBUI_BUILD_HASH`

Type: str
Default: dev-build
Description: Used for identifying the Git SHA of the build for releases.

`WEBUI_BANNERS`

Type: list of dict
Default: []
Description: List of banners to show to users. The format for banners are:

[{"id": "string", "type": "string [info, success, warning, error]", "title": "string", "content": "string", "dismissible": false, "timestamp": 1000}]

Persistence: This environment variable is a PersistentConfig variable.

info

When setting this environment variable in a .env file, make sure to escape the quotes by wrapping the entire value in double quotes and using escaped quotes (\") for the inner quotes. Example:

WEBUI_BANNERS="[{\"id\": \"1\", \"type\": \"warning\", \"title\": \"Your messages are stored.\", \"content\": \"Your messages are stored and may be reviewed by human people. LLM's are prone to hallucinations, check sources.\", \"dismissible\": true, \"timestamp\": 1000}]"

`USE_CUDA_DOCKER`

Type: bool
Default: False
Description: Builds the Docker image with NVIDIA CUDA support. Enables GPU acceleration for local Whisper and embeddings.

`DOCKER`

Type: bool
Default: False
Description: Indicates whether Open WebUI is running inside a Docker container. Used internally for environment detection.

`USE_CUDA`

Type: bool
Default: False
Description: Controls whether to use CUDA acceleration for local models. When set to true, attempts to detect and use available NVIDIA GPUs. The code reads the environment variable USE_CUDA_DOCKER to set this internal boolean variable.

`DEVICE_TYPE`

Type: str
Default: cpu
Description: Specifies the device type for model execution. Automatically set to cuda if CUDA is available and enabled, or mps for Apple Silicon.

`EXTERNAL_PWA_MANIFEST_URL`

Type: str
Default: Empty string (' '), since None is set as default.
Description: When defined as a fully qualified URL (e.g., https://path/to/manifest.webmanifest), requests sent to /manifest.json will use the external manifest file. When not defined, the default manifest.json file will be used.

`ENABLE_TITLE_GENERATION`

Type: bool
Default: True
Description: Enables or disables chat title generation.
Persistence: This environment variable is a PersistentConfig variable.

`LICENSE_KEY`

Type: str
Default: None
Description: Specifies the license key to use (for Enterprise users only).
Persistence: This environment variable is a PersistentConfig variable.

`SSL_ASSERT_FINGERPRINT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the SSL assert fingerprint to use.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_COMPRESSION_MIDDLEWARE`

Type: bool
Default: True
Description: Enables gzip compression middleware for HTTP responses, reducing bandwidth usage and improving load times.

`DEFAULT_PROMPT_SUGGESTIONS`

Type: list of dict
Default: [] (which means to use the built-in default prompt suggestions)
Description: Sets global default prompt suggestions shown to users when starting a new chat. These apply when no model-specific prompt suggestions are configured. Prompt suggestions can also be configured per-model via the Model Editor (see Prompt Suggestions), or globally for all models using the Global Model Defaults feature. The format is:

[{"title": ["Title part 1", "Title part 2"], "content": "prompt"}]

AIOHTTP Client

`AIOHTTP_CLIENT_TIMEOUT`

Type: int
Default: 300
Description: Specifies the timeout duration in seconds for the AIOHTTP client. This impacts things such as connections to Ollama and OpenAI endpoints.

info

This is the maximum amount of time the client will wait for a response before timing out. If set to an empty string (' '), the timeout will be set to None, effectively disabling the timeout and allowing the client to wait indefinitely.

`AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST`

Type: int
Default: 10
Description: Sets the timeout in seconds for fetching the model list from Ollama and OpenAI endpoints. This affects how long Open WebUI waits for each configured endpoint when loading available models.

When to Adjust This Value

Lower the timeout (e.g., 3) if:

You have multiple endpoints configured and want faster failover when one is unreachable
You prefer the UI to load quickly even if some slow endpoints are skipped

Increase the timeout (e.g., 30) if:

Your model servers are slow to respond (e.g., cold starts, large model loading)
You're connecting over high-latency networks
You're using providers like OpenRouter that may have variable response times

Database Persistence

Connection URLs configured via the Admin Settings UI are persisted in the database and take precedence over environment variables. If you save an unreachable URL and the UI becomes unresponsive, you may need to use one of these recovery options:

RESET_CONFIG_ON_START=true - Resets database config to environment variable values on next startup
ENABLE_PERSISTENT_CONFIG=false - Always use environment variables (UI changes won't persist)

See the Model List Loading Issues troubleshooting guide for detailed recovery steps.

`AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST`

Type: int
Description: Sets the timeout in seconds for fetching the model list. This can be useful in cases where network latency requires a longer timeout duration to successfully retrieve the model list.

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER`

Type: int
Default: Inherits AIOHTTP_CLIENT_TIMEOUT when unset
Description: Sets the timeout in seconds for executing tool server API calls (OpenAPI/MCP proxy calls made by Open WebUI). Use this to control how long Open WebUI waits for actual tool execution responses.

info

If this variable is unset or invalid, Open WebUI falls back to AIOHTTP_CLIENT_TIMEOUT.

`AIOHTTP_CLIENT_SESSION_SSL`

Type: bool
Default: True
Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs (e.g., Ollama Embeddings).

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA`

Type: int
Default: 10
Description: Sets the timeout in seconds for retrieving tool server metadata/configuration (for example, loading server data/spec information).

`AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL`

Type: bool
Default: True
Description: Controls SSL/TLS verification specifically for tool server connections via AIOHTTP client.

`REQUESTS_VERIFY`

Type: bool
Default: True
Description: Controls SSL/TLS verification for synchronous requests (e.g., Tika, External Reranker). Set to False to bypass certificate verification for self-signed certificates.

Directories

`DATA_DIR`

Type: str
Default: ./data
Description: Specifies the base directory for data storage, including uploads, cache, vector database, etc.

`FONTS_DIR`

Type: str
Description: Specifies the directory for fonts.

`FRONTEND_BUILD_DIR`

Type: str
Default: ../build
Description: Specifies the location of the built frontend files.

`STATIC_DIR`

Type: str
Default: ./static
Description: Specifies the directory for static files, such as the favicon.

Logging

`GLOBAL_LOG_LEVEL`

Type: str
Default: INFO
Description: Sets the global logging level for all Open WebUI components. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.

`LOG_FORMAT`

Type: str
Default: Not set (plain-text logging)
Description: Controls the log output format. Set to json to switch all stdout logging to single-line JSON objects, suitable for log aggregators like Loki, Fluentd, CloudWatch, and Datadog. When set to json, the ASCII startup banner is also suppressed to keep the log stream parseable. Any other value (or unset) uses the default plain-text format. See the JSON Logging documentation for details on log fields and examples.

`ENABLE_AUDIT_STDOUT`

Type: bool
Default: False
Description: Controls whether audit logs are output to stdout (console). Useful for containerized environments where logs are collected from stdout.

`ENABLE_AUDIT_LOGS_FILE`

Type: bool
Default: True
Description: Controls whether audit logs are written to a file. When enabled, logs are written to the location specified by AUDIT_LOGS_FILE_PATH.

`AUDIT_LOGS_FILE_PATH`

Type: str
Default: ${DATA_DIR}/audit.log
Description: Configures where the audit log file is stored. Enables storing logs in separate volumes or custom locations for better organization and persistence.
Example: /var/log/openwebui/audit.log, /mnt/logs/audit.log

`AUDIT_LOG_FILE_ROTATION_SIZE`

Type: str
Default: 10MB
Description: Specifies the maximum size of the audit log file before rotation occurs (e.g., 10MB, 100MB, 1GB).

`AUDIT_UVICORN_LOGGER_NAMES`

Type: str
Default: uvicorn.access
Description: Comma-separated list of logger names to capture for audit logging. Defaults to Uvicorn's access logger.

`AUDIT_LOG_LEVEL`

Type: str
Default: NONE
Options: NONE, METADATA, REQUEST, REQUEST_RESPONSE
Description: Controls the verbosity level of audit logging. METADATA logs basic request info, REQUEST includes request bodies, REQUEST_RESPONSE includes both requests and responses.

`MAX_BODY_LOG_SIZE`

Type: int
Default: 2048
Description: Sets the maximum size in bytes for request/response bodies in audit logs. Bodies larger than this are truncated.

`AUDIT_EXCLUDED_PATHS`

Type: str
Default: /chats,/chat,/folders
Description: Comma-separated list of URL paths to exclude from audit logging (blacklist mode). Paths are matched without leading slashes against /api/ and /api/v1/ prefixed routes. Ignored when AUDIT_INCLUDED_PATHS is set.

`AUDIT_INCLUDED_PATHS`

Type: str
Default: Empty string (disabled)
Description: Comma-separated list of URL paths to include in audit logging (whitelist mode). When set, only matching paths are audited and AUDIT_EXCLUDED_PATHS is ignored. Paths are matched without leading slashes against /api/ and /api/v1/ prefixed routes. Auth endpoints (signin, signout, signup) are always logged regardless of filtering mode.

Whitelist vs Blacklist

By default, audit logging uses blacklist mode — all paths are logged except those in AUDIT_EXCLUDED_PATHS. If you set AUDIT_INCLUDED_PATHS, it switches to whitelist mode — only the specified paths are logged. If both are set, whitelist mode takes precedence and a warning is logged at startup.

Ollama

`ENABLE_OLLAMA_API`

Type: bool
Default: True
Description: Enables the use of Ollama APIs.
Persistence: This environment variable is a PersistentConfig variable.

`OLLAMA_BASE_URL` (`OLLAMA_API_BASE_URL` is deprecated)

Type: str
Default: http://localhost:11434
Docker Default:
- If K8S_FLAG is set: http://ollama-service.open-webui.svc.cluster.local:11434
- If USE_OLLAMA_DOCKER=True: http://localhost:11434
- Else http://host.docker.internal:11434
Description: Configures the Ollama backend URL.

`OLLAMA_BASE_URLS`

Type: str
Description: Configures load-balanced Ollama backend hosts, separated by ;. See OLLAMA_BASE_URL. Takes precedence overOLLAMA_BASE_URL.
Example: http://host-one:11434;http://host-two:11434
Persistence: This environment variable is a PersistentConfig variable.

`USE_OLLAMA_DOCKER`

Type: bool
Default: False
Description: Builds the Docker image with a bundled Ollama instance.

`K8S_FLAG`

Type: bool
Default: False
Description: If set, assumes Helm chart deployment and sets OLLAMA_BASE_URL to http://ollama-service.open-webui.svc.cluster.local:11434

OpenAI

`ENABLE_OPENAI_API`

Type: bool
Default: True
Description: Enables the use of OpenAI APIs.
Persistence: This environment variable is a PersistentConfig variable.

`OPENAI_API_BASE_URL`

Type: str
Default: https://api.openai.com/v1
Description: Configures the OpenAI base API URL.
Persistence: This environment variable is a PersistentConfig variable.

`OPENAI_API_BASE_URLS`

Type: str
Description: Supports balanced OpenAI base API URLs, semicolon-separated.
Example: http://host-one:11434;http://host-two:11434
Persistence: This environment variable is a PersistentConfig variable.

`OPENAI_API_KEY`

Type: str
Description: Sets the OpenAI API key.
Example: sk-124781258123
Persistence: This environment variable is a PersistentConfig variable.

`OPENAI_API_KEYS`

Type: str
Description: Supports multiple OpenAI API keys, semicolon-separated.
Example: sk-124781258123;sk-4389759834759834
Persistence: This environment variable is a PersistentConfig variable.

Tasks

`TASK_MODEL`

Type: str
Description: The default model to use for tasks such as title and web search query generation when using Ollama models.
Persistence: This environment variable is a PersistentConfig variable.

`TASK_MODEL_EXTERNAL`

Type: str
Description: The default model to use for tasks such as title and web search query generation when using OpenAI-compatible endpoints.
Persistence: This environment variable is a PersistentConfig variable.

`TITLE_GENERATION_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use when generating chat titles.
Default: The value of DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate a concise, 3-5 word title with an emoji summarizing the chat history.

### Guidelines:
- The title should clearly represent the main theme or subject of the conversation.
- Use emojis that enhance understanding of the topic, but avoid quotation marks or special formatting.
- Write the title in the chat's primary language; default to English if multilingual.
- Prioritize accuracy over excessive creativity; keep it clear and simple.

### Output:
JSON format: { "title": "your concise title here" }

### Examples:
- { "title": "📉 Stock Market Trends" },
- { "title": "🍪 Perfect Chocolate Chip Recipe" },
- { "title": "Evolution of Music Streaming" },
- { "title": "Remote Work Productivity Tips" },
- { "title": "Artificial Intelligence in Healthcare" },
- { "title": "🎮 Video Game Development Insights" }

### Chat History:
<chat_history>
{{MESSAGES:END:2}}
</chat_history>

Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_FOLLOW_UP_GENERATION`

Type: bool
Default: True
Description: Enables or disables follow up generation.
Persistence: This environment variable is a PersistentConfig variable.

`FOLLOW_UP_GENERATION_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use for generating several relevant follow-up questions.
Default: The value of DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE:

### Task:
Suggest 3-5 relevant follow-up questions or prompts that the user might naturally ask next in this conversation as a **user**, based on the chat history, to help continue or deepen the discussion.

### Guidelines:
- Write all follow-up questions from the user’s point of view, directed to the assistant.
- Make questions concise, clear, and directly related to the discussed topic(s).
- Only suggest follow-ups that make sense given the chat content and do not repeat what was already covered.
- If the conversation is very short or not specific, suggest more general (but relevant) follow-ups the user might ask.
- Use the conversation's primary language; default to English if multilingual.
- Response must be a JSON array of strings, no extra text or formatting.

### Output:
JSON format: { "follow_ups": ["Question 1?", "Question 2?", "Question 3?"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>"

Persistence: This environment variable is a PersistentConfig variable.

`TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE`

Type: str
Description: Prompt to use when calling tools.
Default: The value of DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE environment variable.

DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE:

Available Tools: {{TOOLS}}

Your task is to choose and return the correct tool(s) from the list of available tools based on the query. Follow these guidelines:

- Return only the JSON object, without any additional text or explanation.

- If no tools match the query, return an empty array:
   {
     "tool_calls": []
   }

- If one or more tools match the query, construct a JSON response containing a "tool_calls" array with objects that include:
   - "name": The tool's name.
   - "parameters": A dictionary of required parameters and their corresponding values.

The format for the JSON response is strictly:
{
  "tool_calls": [
    {"name": "toolName1", "parameters": {"key1": "value1"}},
    {"name": "toolName2", "parameters": {"key2": "value2"}}
  ]
}

Persistence: This environment variable is a PersistentConfig variable.

Code Execution

`ENABLE_CODE_EXECUTION`

Type: bool
Default: True
Description: Enables or disables code execution.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_ENGINE`

Type: str
Default: pyodide
Description: Specifies the code execution engine to use.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_JUPYTER_URL`

Type: str
Default: None
Description: Specifies the Jupyter URL to use for code execution.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_JUPYTER_AUTH`

Type: str
Default: None
Description: Specifies the Jupyter authentication method to use for code execution.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_JUPYTER_AUTH_TOKEN`

Type: str
Default: None
Description: Specifies the Jupyter authentication token to use for code execution.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_JUPYTER_AUTH_PASSWORD`

Type: str
Default: None
Description: Specifies the Jupyter authentication password to use for code execution.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_EXECUTION_JUPYTER_TIMEOUT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the timeout for Jupyter code execution.
Persistence: This environment variable is a PersistentConfig variable.

Code Interpreter

`ENABLE_CODE_INTERPRETER`

Type: bool
Default: True
Description: Enables or disables code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_ENGINE`

Type: str
Default: pyodide
Description: Specifies the code interpreter engine to use.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_BLACKLISTED_MODULES`

Type: str (comma-separated list of module names)
Default: None
Description: Specifies a comma-separated list of Python modules that are blacklisted and cannot be imported or used within the code interpreter. This enhances security by preventing access to potentially sensitive or system-level functionalities.

`CODE_INTERPRETER_PROMPT_TEMPLATE`

Type: str
Default: None
Description: Specifies the prompt template to use for code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_JUPYTER_URL`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter URL to use for code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_JUPYTER_AUTH`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication method to use for code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_JUPYTER_AUTH_TOKEN`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication token to use for code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_JUPYTER_AUTH_PASSWORD`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Jupyter authentication password to use for code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

`CODE_INTERPRETER_JUPYTER_TIMEOUT`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the timeout for the Jupyter code interpreter.
Persistence: This environment variable is a PersistentConfig variable.

Direct Connections (OpenAPI/MCPO Tool Servers)

`ENABLE_DIRECT_CONNECTIONS`

Type: bool
Default: True
Description: Enables or disables direct connections.
Persistence: This environment variable is a PersistentConfig variable.

`TOOL_SERVER_CONNECTIONS`

Type: str (JSON array)
Default: []
Description: Specifies a JSON array of tool server connection configurations. Each connection should define the necessary parameters to connect to external tool servers that implement the OpenAPI/MCPO protocol. For mcpo-backed routes, path should point at the mounted tool route. The JSON must be properly formatted or it will fallback to an empty array.
Field reference:
- url: the server base URL.
- path: the specific tool route exposed by the server.
- auth_type: the authentication mode for the connection.
- key: the API key or token used by the selected auth mode.
- config: per-connection configuration object, such as { "enable": true }.
- info: optional metadata shown in the UI, such as the connection name and description.
- spec_type / spec: OpenAPI spec location details when the connection is backed by a spec URL or file.
Example:

[
  {
    "type": "openapi",
    "url": "example-url",
    "spec_type": "url",
    "spec": "",
    "path": "openapi.json",
    "auth_type": "none",
    "key": "",
    "config": { "enable": true },
    "info": {
      "id": "",
      "name": "example-server",
      "description": "MCP server description."
    }
  }
]

Persistence: This environment variable is a PersistentConfig variable.

warning

The JSON data structure of TOOL_SERVER_CONNECTIONS might evolve over time as new features are added.

Terminal Server

`TERMINAL_SERVER_CONNECTIONS`

Type: str (JSON array)
Default: []
Description: Specifies a JSON array of terminal server connection configurations. Each connection defines the parameters needed to connect to an Open Terminal instance or a Terminals orchestrator. Unlike user-level tool server connections, these are admin-configured and proxied through Open WebUI, which means the terminal URL and API key are never exposed to the browser. Supports group-based access control via access_grants.
Example (direct Open Terminal connection):

[
  {
    "id": "unique-id",
    "url": "http://open-terminal:8000",
    "key": "your-api-key",
    "name": "Dev Terminal",
    "auth_type": "bearer",
    "config": {
      "access_grants": []
    }
  }
]

Example (Terminals orchestrator connection):

[
  {
    "id": "terminals",
    "url": "http://terminals-orchestrator:8080",
    "key": "your-api-key",
    "name": "Terminals",
    "auth_type": "bearer",
    "config": {
      "access_grants": [
        {"principal_type": "user", "principal_id": "*", "permission": "read"}
      ]
    }
  }
]

Persistence: This environment variable is a PersistentConfig variable.

Helm chart auto-configuration

When deploying on Kubernetes with the Open WebUI Helm chart and terminals.enabled: true, this variable is set automatically to point at the in-cluster orchestrator service. See the Terminals (Orchestrator) guide for details.

warning

The JSON data structure of TERMINAL_SERVER_CONNECTIONS might evolve over time as new features are added.

Autocomplete

`ENABLE_AUTOCOMPLETE_GENERATION`

Type: bool
Default: True
Description: Enables or disables autocomplete generation.
Persistence: This environment variable is a PersistentConfig variable.

info

When enabling ENABLE_AUTOCOMPLETE_GENERATION, ensure that you also configure AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH and AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE accordingly.

`AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH`

Type: int
Default: -1
Description: Sets the maximum input length for autocomplete generation.
Persistence: This environment variable is a PersistentConfig variable.

`AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: The value of the DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE:

### Task:
You are an autocompletion system. Continue the text in `<text>` based on the **completion type** in `<type>` and the given language.

### **Instructions**:
1. Analyze `<text>` for context and meaning.
2. Use `<type>` to guide your output:
   - **General**: Provide a natural, concise continuation.
   - **Search Query**: Complete as if generating a realistic search query.
3. Start as if you are directly continuing `<text>`. Do **not** repeat, paraphrase, or respond as a model. Simply complete the text.
4. Ensure the continuation:
   - Flows naturally from `<text>`.
   - Avoids repetition, overexplaining, or unrelated ideas.
5. If unsure, return: `{ "text": "" }`.

### **Output Rules**:
- Respond only in JSON format: `{ "text": "<your_completion>" }`.

### **Examples**:

#### Example 1:
Input:
<type>General</type>
<text>The sun was setting over the horizon, painting the sky</text>
Output:
{ "text": "with vibrant shades of orange and pink." }

#### Example 2:
Input:
<type>Search Query</type>
<text>Top-rated restaurants in</text>
Output:
{ "text": "New York City for Italian cuisine." }

---

### Context:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
<type>{{TYPE}}</type>
<text>{{PROMPT}}</text>

#### Output:

Description: Sets the prompt template for autocomplete generation.
Persistence: This environment variable is a PersistentConfig variable.

Evaluation Arena Model

`ENABLE_EVALUATION_ARENA_MODELS`

Type: bool
Default: True
Description: Enables or disables evaluation arena models.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_MESSAGE_RATING`

Type: bool
Default: True
Description: Enables message rating feature.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_COMMUNITY_SHARING`

Type: bool
Default: True
Description: Controls whether users can share content with the Open WebUI Community and access community resources. When enabled, this setting shows the following UI elements across the application:
- Prompts Workspace: "Made by Open WebUI Community" section with a link to discover community prompts, and a "Share" button in the prompt menu dropdown
- Tools Workspace: "Made by Open WebUI Community" section with a link to discover community tools, and a "Share" button in the tool menu dropdown
- Models Workspace: "Made by Open WebUI Community" section with a link to discover community model presets, and a "Share" button in the model menu dropdown
- Functions Admin: "Made by Open WebUI Community" section with a link to discover community functions
- Share Chat Modal: "Share to Open WebUI Community" button when sharing a chat conversation
- Evaluation Feedbacks: "Share to Open WebUI Community" button for contributing feedback history to the community leaderboard
- Stats Sync Modal: Enables syncing usage statistics with the community
Persistence: This environment variable is a PersistentConfig variable.

info

When ENABLE_COMMUNITY_SHARING is set to False, all community sharing buttons and community resource discovery sections will be hidden from the UI. Users will still be able to export content locally, but the option to share directly to the Open WebUI Community will not be available.

Tags Generation

`ENABLE_TAGS_GENERATION`

Type: bool
Default: True
Description: Enables or disables tag generation.
Persistence: This environment variable is a PersistentConfig variable.

`TAGS_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: The value of DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate 1-3 broad tags categorizing the main themes of the chat history, along with 1-3 more specific subtopic tags.

### Guidelines:
- Start with high-level domains (e.g., Science, Technology, Philosophy, Arts, Politics, Business, Health, Sports, Entertainment, Education)
- Consider including relevant subfields/subdomains if they are strongly represented throughout the conversation
- If content is too short (less than 3 messages) or too diverse, use only ["General"]
- Use the chat's primary language; default to English if multilingual
- Prioritize accuracy over specificity

### Output:
JSON format: { "tags": ["tag1", "tag2", "tag3"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>

Description: Sets the prompt template for tag generation.
Persistence: This environment variable is a PersistentConfig variable.

API Key Endpoint Restrictions

`ENABLE_API_KEYS`

Type: bool
Default: False
Description: Enables the API key creation feature, allowing users to generate API keys for programmatic access to Open WebUI.
Persistence: This environment variable is a PersistentConfig variable.

info

This variable replaces the deprecated ENABLE_API_KEY environment variable.

info

For API Key creation (and the API keys themselves) to work:

Enable API keys globally using this setting (ENABLE_API_KEYS)
For non-admin users, grant the "API Keys" permission via Default Permissions or User Groups

Note: Administrators can generate API keys whenever ENABLE_API_KEYS is enabled, even without features.api_keys.

`ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS`

Type: bool
Default: False
Description: Enables API key endpoint restrictions for added security and configurability, allowing administrators to limit which endpoints can be accessed using API keys.
Persistence: This environment variable is a PersistentConfig variable.

info

This variable replaces the deprecated ENABLE_API_KEY_ENDPOINT_RESTRICTIONS environment variable.

`API_KEYS_ALLOWED_ENDPOINTS`

Type: str
Description: Specifies a comma-separated list of allowed API endpoints when API key endpoint restrictions are enabled.
Example: /api/v1/messages,/api/v1/channels,/api/v1/chat/completions
Persistence: This environment variable is a PersistentConfig variable.

note

The value of API_KEYS_ALLOWED_ENDPOINTS should be a comma-separated list of endpoint URLs, such as /api/v1/messages, /api/v1/channels.

info

This variable replaces the deprecated API_KEY_ALLOWED_ENDPOINTS environment variable.

Model Caching

`ENABLE_BASE_MODELS_CACHE`

Type: bool
Default: False
Description: When enabled, caches the list of base models from connected Ollama and OpenAI-compatible endpoints in memory. This reduces the number of API calls made to external model providers when loading the model selector, improving performance particularly for deployments with many users or slow connections to model endpoints. Can also be configured from Admin Panel > Settings > Connections > "Cache Base Model List".
Persistence: This environment variable is a PersistentConfig variable.

How the cache works:

Initialization: When enabled, base models are fetched and cached during application startup.
Storage: The cache is stored in application memory (app.state.BASE_MODELS).
Cache Hit: Subsequent requests for models return the cached list without contacting external endpoints.
Cache Refresh: The cache is refreshed when:
- The application restarts
- The connection settings are saved in the Admin Panel > Settings > Connections (clicking the Save button on the bottom right will trigger a refresh and update the cache with the newly fetched models)
No TTL: There is no automatic time-based expiration.

Performance Consideration

Enable this setting in production environments where model lists are relatively stable. For development environments or when frequently adding/removing models from Ollama, you may prefer to leave it disabled for real-time model discovery.

`MODELS_CACHE_TTL`

Type: int
Default: 1
Description: Sets the cache time-to-live in seconds for model list responses from OpenAI and Ollama endpoints. This reduces API calls by caching the available models list for the specified duration. Set to empty string to disable caching entirely.

This caches the external model lists retrieved from configured OpenAI-compatible and Ollama API endpoints (not Open WebUI's internal model configurations). Higher values improve performance by reducing redundant API requests to external providers but may delay visibility of newly added or removed models on those endpoints. A value of 0 disables caching and forces fresh API calls each time.

High-Traffic Recommendation

In high-traffic scenarios, increasing this value (e.g., to 300 seconds) can significantly reduce load on external API endpoints while still providing reasonably fresh model data.

Two Caching Mechanisms

Open WebUI has two model caching mechanisms that work independently:

Setting	Type	Default	Refresh Trigger
`ENABLE_BASE_MODELS_CACHE`	In-memory	`False`	App restart OR Admin Save
`MODELS_CACHE_TTL`	TTL-based	`1` second	Automatic after TTL expires

For maximum performance, enable both: ENABLE_BASE_MODELS_CACHE=True with MODELS_CACHE_TTL=300.

`JWT_EXPIRES_IN`

Type: str
Default: 4w
Description: Sets the JWT expiration time in seconds. Valid time units: s, m, h, d, w or -1 for no expiration.
Persistence: This environment variable is a PersistentConfig variable.

warning

Setting JWT_EXPIRES_IN to -1 disables JWT expiration, making issued tokens valid forever. This is extremely dangerous in production and exposes your system to severe security risks if tokens are leaked or compromised.

Always set a reasonable expiration time in production environments (e.g., 3600s, 1h, 7d etc.) to limit the lifespan of authentication tokens.

NEVER use -1 in a production environment.

If you have already deployed with JWT_EXPIRES_IN=-1, you can rotate or change your WEBUI_SECRET_KEY to immediately invalidate all existing tokens.

Security Variables

`ENABLE_FORWARD_USER_INFO_HEADERS`

type: bool
Default: False
Description: Forwards user and session information as HTTP headers to OpenAI API, Ollama API, MCP servers, and Tool servers. If enabled, the following headers are forwarded:
- X-OpenWebUI-User-Name
- X-OpenWebUI-User-Id
- X-OpenWebUI-User-Email
- X-OpenWebUI-User-Role
- X-OpenWebUI-Chat-Id
- X-OpenWebUI-Message-Id

This enables per-user authorization, auditing, rate limiting, and request tracing on external services. The chat and message ID headers are also required for external tool event emitting.

`FORWARD_USER_INFO_HEADER_USER_NAME`

Type: str
Default: X-OpenWebUI-User-Name
Description: Customizes the header name used to forward the user's display name. Change this if your infrastructure requires a specific header prefix.

`FORWARD_USER_INFO_HEADER_USER_ID`

Type: str
Default: X-OpenWebUI-User-Id
Description: Customizes the header name used to forward the user's ID.

`FORWARD_USER_INFO_HEADER_USER_EMAIL`

Type: str
Default: X-OpenWebUI-User-Email
Description: Customizes the header name used to forward the user's email address.

`FORWARD_USER_INFO_HEADER_USER_ROLE`

Type: str
Default: X-OpenWebUI-User-Role
Description: Customizes the header name used to forward the user's role.

`FORWARD_SESSION_INFO_HEADER_CHAT_ID`

Type: str
Default: X-OpenWebUI-Chat-Id
Description: Customizes the header name used to forward the current chat/session ID.

`FORWARD_SESSION_INFO_HEADER_MESSAGE_ID`

Type: str
Default: X-OpenWebUI-Message-Id
Description: Customizes the header name used to forward the current message ID. This header is required for external tool event emitting.

Custom Header Prefix

Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with X-Amzn-Bedrock-AgentCore-Runtime-Custom-:

FORWARD_USER_INFO_HEADER_USER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name
FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id
FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email
FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role
FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id
FORWARD_SESSION_INFO_HEADER_MESSAGE_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Message-Id

`ENABLE_WEB_LOADER_SSL_VERIFICATION`

Type: bool
Default: True
Description: Bypass SSL Verification for RAG on Websites.
Persistence: This environment variable is a PersistentConfig variable.

`WEBUI_SESSION_COOKIE_SAME_SITE`

Type: str
Options:
- lax - Sets the SameSite attribute to lax, allowing session cookies to be sent with requests initiated by third-party websites.
- strict - Sets the SameSite attribute to strict, blocking session cookies from being sent with requests initiated by third-party websites.
- none - Sets the SameSite attribute to none, allowing session cookies to be sent with requests initiated by third-party websites, but only over HTTPS.
Default: lax
Description: Sets the SameSite attribute for session cookies.

warning

When ENABLE_OAUTH_SIGNUP is enabled, setting WEBUI_SESSION_COOKIE_SAME_SITE to strict can cause login failures. This is because Open WebUI uses a session cookie to validate the callback from the OAuth provider, which helps prevent CSRF attacks.

However, a strict session cookie is not sent with the callback request, leading to potential login issues. If you experience this problem, use the default lax value instead.

`WEBUI_SESSION_COOKIE_SECURE`

Type: bool
Default: False
Description: Sets the Secure attribute for session cookies if set to True.

`WEBUI_AUTH_COOKIE_SAME_SITE`

Type: str
Options:
- lax - Sets the SameSite attribute to lax, allowing auth cookies to be sent with requests initiated by third-party websites.
- strict - Sets the SameSite attribute to strict, blocking auth cookies from being sent with requests initiated by third-party websites.
- none - Sets the SameSite attribute to none, allowing auth cookies to be sent with requests initiated by third-party websites, but only over HTTPS.
Default: lax
Description: Sets the SameSite attribute for auth cookies.

info

If the value is not set, WEBUI_SESSION_COOKIE_SAME_SITE will be used as a fallback.

`WEBUI_AUTH_COOKIE_SECURE`

Type: bool
Default: False
Description: Sets the Secure attribute for auth cookies if set to True.

info

If the value is not set, WEBUI_SESSION_COOKIE_SECURE will be used as a fallback.

`WEBUI_AUTH`

Type: bool
Default: True
Description: This setting enables or disables authentication.

danger

If set to False, authentication will be disabled for your Open WebUI instance. However, it's important to note that turning off authentication is only possible for fresh installations without any existing users. If there are already users registered, you cannot disable authentication directly. Ensure that no users are present in the database if you intend to turn off WEBUI_AUTH.

`ENABLE_PASSWORD_VALIDATION`

Type: bool
Default: False
Description: Enables password complexity validation for user accounts. When enabled, passwords must meet the complexity requirements defined by PASSWORD_VALIDATION_REGEX_PATTERN during signup, password updates, and user creation operations. This helps enforce stronger password policies across the application.

info

Password validation is applied to:

New user registration (signup)
Password changes through user settings
Admin-initiated user creation
Password resets

Existing users with passwords that don't meet the new requirements are not automatically forced to update their passwords, but will need to meet the requirements when they next change their password.

`PASSWORD_VALIDATION_REGEX_PATTERN`

Type: str
Default: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^\w\s]).{8,}$
Description: Regular expression pattern used to validate password complexity when ENABLE_PASSWORD_VALIDATION is enabled. The default pattern requires passwords to be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one special character.

warning

Custom Pattern Considerations

When defining a custom regex pattern, ensure it:

Is a valid regular expression that Python's re module can compile
Balances security requirements with user experience
Is thoroughly tested before deployment to avoid locking users out

Invalid regex patterns will cause password validation to fail, potentially preventing user registration and password changes.

`PASSWORD_VALIDATION_HINT`

Type: str
Default: "" (empty string)
Description: Custom hint message displayed to users when their password fails validation. This message appears in error dialogs during signup, password changes, and admin user creation when the password doesn't meet the requirements defined by PASSWORD_VALIDATION_REGEX_PATTERN. Use this to explain your specific password requirements in user-friendly terms.
Example: Password must be at least 12 characters with uppercase, lowercase, number, and special character.

tip

When setting a custom PASSWORD_VALIDATION_REGEX_PATTERN, always set PASSWORD_VALIDATION_HINT to explain the requirements in plain language. Without a hint, users will only see a generic "Invalid password" error with no guidance on what's required.

`WEBUI_SECRET_KEY`

Type: str
Default: t0p-s3cr3t
Docker Default: Randomly generated on first start
Description: Overrides the randomly generated string used for JSON Web Token and encryption of sensitive data (like OAuth tokens for MCP).

Critical for Docker/Production

You MUST set WEBUI_SECRET_KEY to a secure, persistent value.

If you do NOT set this:

It will be randomly generated each time the container restarts/recreates.
All OAuth sessions will become invalid.
MCP Tools will break (Error: Error decrypting tokens) because they cannot decrypt the tokens stored with the previous key.
You will be logged out.

Do not leave this unset in production.

warning

Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS

When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set this variable. Without it, the following issues will occur:

Session management will fail across workers
Application state will be inconsistent between instances
Websocket connections will not function properly in distributed setups
Users may experience intermittent authentication failures

`ENABLE_VERSION_UPDATE_CHECK`

Type: bool
Default: True
Description: When enabled, the application makes automatic update checks and notifies you about version updates.

info

If OFFLINE_MODE is enabled, this ENABLE_VERSION_UPDATE_CHECK flag is always set to false automatically.

`OFFLINE_MODE`

Type: bool
Default: False
Description: Disables Open WebUI's network connections for update checks and automatic model downloads.

info

Disabled when enabled:

Automatic version update checks (see flag ENABLE_VERSION_UPDATE_CHECK)
Downloads of embedding models from Hugging Face Hub
- If you did not download an embedding model prior to activating OFFLINE_MODE any RAG, web search and document analysis functionality may not work properly
Update notifications in the UI (see flag ENABLE_VERSION_UPDATE_CHECK)

Still functional:

External LLM API connections (OpenAI, etc.)
OAuth authentication providers
Web search and RAG with external APIs

Read more about offline mode in the offline mode guide.

`HF_HUB_OFFLINE`

Type: int
Default: 0
Description: Tells Hugging Face whether we want to launch in offline mode, so to not connect to hugging face and prevent all automatic model downloads

info

Downloads of models, sentence transformers and other configurable items will NOT WORK when this is set to 1. RAG will also not work on a default installation, if this is set to True.

`RESET_CONFIG_ON_START`

Type: bool
Default: False
Description: Resets the config.json file on startup.

`SAFE_MODE`

Type: bool
Default: False
Description: Enables safe mode, which disables potentially unsafe features, deactivating all functions.

`CORS_ALLOW_ORIGIN`

Type: str
Default: *
Description: Sets the allowed origins for Cross-Origin Resource Sharing (CORS). Smicolon ';' separated list of allowed origins.

warning

This variable is required to be set, otherwise you may experience Websocket issues and weird "{}" responses or "Unexpected token 'd', "data: {"id"... is not valid JSON".

info

If you experience Websocket issues, check the logs of Open WebUI. If you see lines like this engineio.base_server:_log_error_once:354 - https://yourdomain.com is not an accepted origin. then you need to configure your CORS_ALLOW_ORIGIN more broadly.

Example: CORS_ALLOW_ORIGIN: "https://yourdomain.com;http://yourdomain.com;https://yourhostname;http://youripaddress;http://localhost:3000"

Add all valid IPs, Domains and Hostnames one might access your Open WebUI to the variable. Once you did, no more websocket issues or warnings in the console should occur.

`CORS_ALLOW_CUSTOM_SCHEME`

Type str
Default: "" (empty string)
Description: Sets a list of further allowed schemes for Cross-Origin Resource Sharing (CORS). Allows you to specify additional custom URL schemes, beyond the standard http and https, that are permitted as valid origins for Cross-Origin Resource Sharing (CORS).

info

This is particularly useful for scenarios such as:

Integrating with desktop applications that use custom protocols (e.g., app://, custom-app-scheme://).
Local development environments or testing setups that might employ non-standard schemes (e.g., file:// if applicable, or electron://).

Provide a semicolon-separated list of scheme names without the ://. For example: app;file;electron;my-custom-scheme.

When configured, these custom schemes will be validated alongside http and https for any origins specified in CORS_ALLOW_ORIGIN.

`RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE`

Type: bool
Default: False
Description: Determines whether to allow custom models defined on the Hub in their own modeling files.

`RAG_RERANKING_MODEL_TRUST_REMOTE_CODE`

Type: bool
Default: False
Description: Determines whether to allow custom models defined on the Hub in their own. modeling files for reranking.

`RAG_EMBEDDING_MODEL_AUTO_UPDATE`

Type: bool
Default: True
Description: Toggles automatic update of the Sentence-Transformer model.

`RAG_RERANKING_MODEL_AUTO_UPDATE`

Type: bool
Default: True
Description: Toggles automatic update of the reranking model.

Vector Database

`VECTOR_DB`

Type: str
Options:
chroma, elasticsearch, mariadb-vector, milvus, opensearch, pgvector, qdrant, pinecone, s3vector, oracle23ai, weaviate
Default: chroma
Description: Specifies which vector database system to use. This setting determines which vector storage system will be used for managing embeddings.

ChromaDB (Default) Is Not Safe for Multi-Worker or Multi-Replica Deployments

The default ChromaDB configuration uses a local PersistentClient backed by SQLite. SQLite is not fork-safe — when uvicorn forks multiple worker processes (UVICORN_WORKERS > 1), each worker inherits a copy of the same SQLite connection. Concurrent writes from these forked processes cause immediate crashes (Child process died) or database corruption.

This also applies to multi-replica deployments (Kubernetes, Docker Swarm) where multiple containers point at the same ChromaDB data directory.

If you need multiple workers or replicas, you must either:

Switch to a client-server vector database such as PGVector, MariaDB Vector, Milvus, or Qdrant (recommended).
Run ChromaDB as a separate HTTP server and configure CHROMA_HTTP_HOST / CHROMA_HTTP_PORT so that Open WebUI uses an HttpClient instead of the local PersistentClient.

See the Scaling & HA guide for full details.

note

PostgreSQL Dependencies To use pgvector, ensure you have PostgreSQL dependencies installed:

pip install open-webui[all]

info

Only PGVector and ChromaDB will be consistently maintained by the Open WebUI team. The other vector stores are community-added vector databases.

ChromaDB

Local vs. HTTP Mode

By default (when CHROMA_HTTP_HOST is not set), ChromaDB runs as a local PersistentClient using SQLite for storage. This mode is only safe for single-worker, single-instance deployments (UVICORN_WORKERS=1, one replica).

For multi-worker or multi-replica setups, you must configure CHROMA_HTTP_HOST and CHROMA_HTTP_PORT to point to a standalone ChromaDB server, or switch to a different vector database entirely. See the VECTOR_DB warning above.

`CHROMA_TENANT`

Type: str
Default: The value of chromadb.DEFAULT_TENANT (a constant in the chromadb module)
Description: Sets the tenant for ChromaDB to use for RAG embeddings.

`CHROMA_DATABASE`

Type: str
Default: The value of chromadb.DEFAULT_DATABASE (a constant in the chromadb module)
Description: Sets the database in the ChromaDB tenant to use for RAG embeddings.

`CHROMA_HTTP_HOST`

Type: str
Description: Specifies the hostname of a remote ChromaDB Server. Uses a local ChromaDB instance if not set. Setting this variable is required for multi-worker or multi-replica deployments — it switches ChromaDB from the local SQLite-backed PersistentClient to a fork-safe HttpClient.

`CHROMA_HTTP_PORT`

Type: int
Default: 8000
Description: Specifies the port of a remote ChromaDB Server.

`CHROMA_HTTP_HEADERS`

Type: str
Description: A comma-separated list of HTTP headers to include with every ChromaDB request.
Example: Authorization=Bearer heuhagfuahefj,User-Agent=OpenWebUI.

`CHROMA_HTTP_SSL`

Type: bool
Default: False
Description: Controls whether or not SSL is used for ChromaDB Server connections.

`CHROMA_CLIENT_AUTH_PROVIDER`

Type: str
Description: Specifies an authentication provider for remote ChromaDB Server.
Example: chromadb.auth.basic_authn.BasicAuthClientProvider

`CHROMA_CLIENT_AUTH_CREDENTIALS`

Type: str
Description: Specifies auth credentials for remote ChromaDB Server.
Example: username:password

Elasticsearch

`ELASTICSEARCH_API_KEY`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Elasticsearch API key.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_CA_CERTS`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the path to the CA certificates for Elasticsearch.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_CLOUD_ID`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the Elasticsearch cloud ID.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_INDEX_PREFIX`

Type: str
Default: open_webui_collections
Description: Specifies the prefix for the Elasticsearch index.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_PASSWORD`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the password for Elasticsearch.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_URL`

Type: str
Default: https://localhost:9200
Description: Specifies the URL for the Elasticsearch instance.
Persistence: This environment variable is a PersistentConfig variable.

`ELASTICSEARCH_USERNAME`

Type: str
Default: Empty string (' '), since None is set as default.
Description: Specifies the username for Elasticsearch.
Persistence: This environment variable is a PersistentConfig variable.

Milvus

warning

Milvus is not actively maintained by the Open WebUI team. It is an addition by the community and is maintained by the community. If you want to use Milvus, be careful when upgrading Open WebUI (crate backups and snapshots for rollbacks) in case internal changes in Open WebUI lead to breakage.

`MILVUS_URI` (Required)

Type: str
Default: ${DATA_DIR}/vector_db/milvus.db
Example (Remote): http://your-server-ip:19530
Description: Specifies the URI for connecting to the Milvus vector database. This can point to a local or remote Milvus server based on the deployment configuration.

`MILVUS_DB`

Type: str
Default: default
Example: default
Description: Specifies the database to connect to within a Milvus instance.

`MILVUS_TOKEN` (Required for remote connections with authentication)

Type: str
Default: None
Example: root:password (format: username:password)
Description: Specifies an optional connection token for Milvus. Required when connecting to a remote Milvus server with authentication enabled. Format is username:password.

`MILVUS_INDEX_TYPE`

Type: str
Default: HNSW
Options: AUTOINDEX, FLAT, IVF_FLAT, HNSW, DISKANN
Description: Specifies the index type to use when creating a new collection in Milvus. AUTOINDEX is generally recommended for Milvus standalone. HNSW may offer better performance but requires a clustered Milvus setup and is not meant for standalone setups.
Persistence: This environment variable is a PersistentConfig variable.

`MILVUS_METRIC_TYPE`

Type: str
Default: COSINE
Options: COSINE, IP, L2
Description: Specifies the metric type for vector similarity search in Milvus.
Persistence: This environment variable is a PersistentConfig variable.

`MILVUS_HNSW_M`

Type: int
Default: 16
Description: Specifies the M parameter for the HNSW index type in Milvus. This influences the number of bi-directional links created for each new element during construction. Only applicable if MILVUS_INDEX_TYPE is HNSW.
Persistence: This environment variable is a PersistentConfig variable.

`MILVUS_HNSW_EFCONSTRUCTION`

Type: int
Default: 100
Description: Specifies the efConstruction parameter for the HNSW index type in Milvus. This influences the size of the dynamic list for the nearest neighbors during index construction. Only applicable if MILVUS_INDEX_TYPE is HNSW.
Persistence: This environment variable is a PersistentConfig variable.

`MILVUS_IVF_FLAT_NLIST`

Type: int
Default: 128
Description: Specifies the nlist parameter for the IVF_FLAT index type in Milvus. This is the number of cluster units. Only applicable if MILVUS_INDEX_TYPE is IVF_FLAT.
Persistence: This environment variable is a PersistentConfig variable.

`MILVUS_DISKANN_MAX_DEGREE`

Type: int
Default: 56
Description: Sets the max degree for Milvus if Milvus is in DISKANN indexing mode. Generally recommended to leave as is.

`MILVUS_DISKANN_SEARCH_LIST_SIZE`

Type: int
Default: 100
Description: Sets the Milvus DISKANN search list size. Generally recommended to leave as is.

`ENABLE_MILVUS_MULTITENANCY_MODE`

Type: bool
Default: false
Description: Enables multitenancy pattern for Milvus collections management, which significantly reduces RAM usage and computational overhead by consolidating similar vector data structures. Controls whether Milvus uses multitenancy collection architecture. When enabled, all vector data is consolidated into 5 shared collections (memories, knowledge, files, web_search, hash_based) instead of creating individual collections per resource. Data isolation is achieved via a resource_id field rather than collection-level separation.

info

Benefits of multitenancy mode:

Significantly reduced RAM consumption (5 collections vs potentially hundreds)
Lower computational overhead from collection management
Faster cold-start times
Reduced index maintenance burden

Technical implementation:

All memories go into {prefix}_memories
All knowledge bases go into {prefix}_knowledge
All uploaded files go into {prefix}_files
Web search results go into {prefix}_web_search
Hash-based collections go into {prefix}_hash_based
Each entry includes a resource_id field matching the original collection name
Queries automatically filter by resource_id to maintain data isolation

Collection Variable	Default Name (Suffix)	Trigger / Routing Logic in the Code	Purpose
`HASH_BASED_COLLECTION`	`_hash_based`	Collection name is a 63-char hex string (SHA256 hash).	Caching direct URL fetches (Websites) with the `#` feature.
`MEMORY_COLLECTION`	`_memories`	Collection name starts with `user-memory-`.	Storing user-specific long-term memories of the experimental memory system.
`FILE_COLLECTION`	`_files`	Collection name starts with `file-`.	Storing uploaded documents (PDFs, DOCX, etc.).
`WEB_SEARCH_COLLECTION`	`_web_search`	Collection name starts with `web-search-`.	Storing transient results from search engine queries.
`KNOWLEDGE_COLLECTION`	`_knowledge`	Everything else (Default fallback).	Storing explicitly created Knowledge Bases.

info

Migration from Legacy Mode to Multitenancy

What happens when you enable multitenancy when you already have a normal milvus database with data in it:

Existing collections (pattern: open_webui_{collection_name}) remain in Milvus but become inaccessible to Open WebUI
New data is written to the 5 shared multitenancy collections
Application treats knowledge bases as empty until reindexed
Files and memories are NOT automatically migrated to the new collection schema and will appear missing

Clean migration path from normal Milvus to multitenancy milvus:

Before enabling multitenancy, export any critical knowledge content from the UI if possible
Set ENABLE_MILVUS_MULTITENANCY_MODE=true and restart Open WebUI
Navigate to Admin Settings > Documents > Click Reindex Knowledge Base

This rebuilds ONLY knowledge base vectors into the new multitenancy collections Files, user memories, and web search history are NOT migrated by this operation

Verify knowledge bases are accessible and functional

Re-upload files if file-based retrieval is critical (file metadata remains but vectors are not migrated)
User chat memories will need to be regenerated through new conversations

Cleaning up legacy collections: After successful migration (from milvus to multitenancy milvus), legacy collections still consume resources. Remove them manually:

Connect to Milvus using the native client (pymilvus or Attu UI)
Delete all old collections

Current UI limitations:

No one-click "migrate and cleanup" button exists
Vector DB reset from UI (Admin Settings > Documents > Reset Vector Storage/Knowledge) only affects the active mode's collections
Legacy collections require manual cleanup via Milvus client tools

warning

Critical Considerations

Before enabling multitenancy on an existing installation:

Data loss risk: File vectors and user memory vectors are NOT migrated automatically. Only knowledge base content can be reindexed (migrated).
Collection naming dependency: Multitenancy relies on Open WebUI's internal collection naming conventions (user-memory-, file-, web-search-, hash patterns). If Open WebUI changes these conventions in future updates, multitenancy routing may break, causing data corruption or incorrect data retrieval across isolated resources.
No automatic rollback: Disabling multitenancy after data is written will not restore access to the shared collections. Data would need manual extraction and re-import.

For fresh installations, no migration concerns exist

For existing installations with valuable data:

Do not migrate to multitenancy mode if you do not want to handle migration and risk data loss
Understand that files and memories require re-upload/regeneration
Test migration on a backup/staging environment first
Consider if RAM savings justify the migration effort for your use case

To perform a full reset and switch to multitenancy:

Backup any critical knowledge base content externally
Navigate to Admin Settings > Documents
Click Reset Vector Storage/Knowledge (this deletes all active mode collections and stored knowledge metadata)
Set ENABLE_MILVUS_MULTITENANCY_MODE=true
Restart Open WebUI
Re-upload/re-create knowledge bases from scratch

warning

The mapping of multitenancy relies on current Open WebUI naming conventions for collection names.

If Open WebUI changes how it generates collection names (e.g., "user-memory-" prefix, "file-" prefix, web search patterns, or hash formats), this mapping will break and route data to incorrect collections. POTENTIALLY CAUSING HUGE DATA CORRUPTION, DATA CONSISTENCY ISSUES AND INCORRECT DATA MAPPING INSIDE THE DATABASE.

If you use Multitenancy Mode, you should always check for any changes to the collection names and data mapping before upgrading, and upgrade carefully (snapshots and backups for rollbacks)!

`MILVUS_COLLECTION_PREFIX`

Type: str
Default: open_webui
Description: Sets the prefix for Milvus collection names. In multitenancy mode, collections become {prefix}_memories, {prefix}_knowledge, etc. In legacy mode, collections are {prefix}_{collection_name}. Changing this value creates an entirely separate namespace—existing collections with the old prefix become invisible to Open WebUI but remain in Milvus consuming resources. Use this for true multi-instance isolation on a shared Milvus server, not for migration between modes. Milvus only accepts underscores, hyphens/dashes are not possible and will cause errors.

MariaDB Vector

warning

MariaDB Vector is not actively maintained by the Open WebUI team. It is an addition by the community and is maintained by the community. If you want to use MariaDB Vector, be careful when upgrading Open WebUI (create backups and snapshots for rollbacks) in case internal changes in Open WebUI lead to breakage.

note

MariaDB Dependencies

The mariadb Python connector is not included by default — it was removed from the bundled dependencies. To use mariadb-vector, you must install it explicitly:

pip install open-webui[mariadb]

The official Docker image includes the system-level C library (libmariadb-dev) needed to compile the connector, so pip install open-webui[mariadb] will work inside the container without additional system packages. For non-Docker deployments, you must install the MariaDB C connector library (libmariadb-dev on Debian/Ubuntu) before installing the Python driver.

info

MariaDB Vector requires the official MariaDB connector (mariadb+mariadbconnector://...) as the connection scheme. This is mandatory because the official driver provides the correct qmark paramstyle and proper binary binding for VECTOR(n) float32 payloads. Other MySQL-compatible drivers will not work.

Your MariaDB server must support VECTOR and VECTOR INDEX features (MariaDB 11.7+).

`MARIADB_VECTOR_DB_URL`

Type: str
Default: Empty string ("")
Description: Sets the database URL for MariaDB Vector storage. Must use the mariadb+mariadbconnector:// scheme (official MariaDB driver).
Example: mariadb+mariadbconnector://user:password@localhost:3306/openwebui

`MARIADB_VECTOR_INITIALIZE_MAX_VECTOR_LENGTH`

Type: int
Default: 1536
Description: Specifies the maximum vector length (number of dimensions) for the VECTOR(n) column. Must match the dimensionality of your embedding model. Once the table is created, changing this value requires data migration — the backend will refuse to start if the configured dimension differs from the stored column dimension.

`MARIADB_VECTOR_DISTANCE_STRATEGY`

Type: str
Options:
- cosine - Uses vec_distance_cosine() for similarity measurement.
- euclidean - Uses vec_distance_euclidean() for similarity measurement.
Default: cosine
Description: Controls which distance function is used for the VECTOR INDEX and similarity search queries.

`MARIADB_VECTOR_INDEX_M`

Type: int
Default: 8
Description: HNSW index parameter that controls the maximum number of bi-directional connections per layer during index construction (M=<int> in the MariaDB VECTOR INDEX definition). Higher values improve recall but increase index size and build time.

`MARIADB_VECTOR_POOL_SIZE`

Type: int
Default: None
Description: Sets the number of connections to maintain in the MariaDB Vector database connection pool. If not set, uses SQLAlchemy defaults. Setting this to 0 disables connection pooling entirely (uses NullPool).

`MARIADB_VECTOR_POOL_MAX_OVERFLOW`

Type: int
Default: 0
Description: Specifies the maximum number of connections that can be created beyond MARIADB_VECTOR_POOL_SIZE when the pool is exhausted.

`MARIADB_VECTOR_POOL_TIMEOUT`

Type: int
Default: 30
Description: Sets the timeout in seconds for acquiring a connection from the MariaDB Vector pool.

`MARIADB_VECTOR_POOL_RECYCLE`

Type: int
Default: 3600
Description: Specifies the time in seconds after which connections are recycled in the MariaDB Vector pool to prevent stale connections.

OpenSearch

`OPENSEARCH_CERT_VERIFY`

Type: bool
Default: False
Description: Enables or disables OpenSearch certificate verification.

`OPENSEARCH_PASSWORD`

Type: str
Default: None
Description: Sets the password for OpenSearch.

`OPENSEARCH_SSL`

Type: bool
Default: True
Description: Enables or disables SSL for OpenSearch.

`OPENSEARCH_URI`

Type: str
Default: https://localhost:9200
Description: Sets the URI for OpenSearch.

`OPENSEARCH_USERNAME`

Type: str
Default: None
Description: Sets the username for OpenSearch.

PGVector

note

PostgreSQL Dependencies To use pgvector, ensure you have PostgreSQL dependencies installed:

pip install open-webui[all]

`PGVECTOR_DB_URL`

Type: str
Default: The value of the DATABASE_URL environment variable
Description: Sets the database URL for model storage.

`PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH`

Type: str
Default: 1536
Description: Specifies the maximum vector length for PGVector initialization.

`PGVECTOR_CREATE_EXTENSION`

Type: str
Default true
Description: Creates the vector extension in the database

info

If set to false, open-webui will assume the postgreSQL database where embeddings will be stored is pre-configured with the vector extension. This also allows open-webui to run as a non superuser database user.

`PGVECTOR_INDEX_METHOD`

Type: str
Options:
- ivfflat - Uses inverted file with flat compression, better for datasets with many dimensions.
- hnsw - Uses Hierarchical Navigable Small World graphs, generally provides better query performance.
Default: Not specified (pgvector will use its default)
Description: Specifies the index method for pgvector. The choice affects query performance and index build time.
Persistence: This environment variable is a PersistentConfig variable.

info

When choosing an index method, consider your dataset size and query patterns. HNSW generally provides better query performance but uses more memory, while IVFFlat can be more memory-efficient for larger datasets.

`PGVECTOR_HNSW_M`

Type: int
Default: 16
Description: HNSW index parameter that controls the maximum number of bi-directional connections per layer during index construction. Higher values improve recall but increase index size and build time. Only applicable when PGVECTOR_INDEX_METHOD is set to hnsw.
Persistence: This environment variable is a PersistentConfig variable.

`PGVECTOR_HNSW_EF_CONSTRUCTION`

Type: int
Default: 64
Description: HNSW index parameter that controls the size of the dynamic candidate list during index construction. Higher values improve index quality but increase build time. Only applicable when PGVECTOR_INDEX_METHOD is set to hnsw.
Persistence: This environment variable is a PersistentConfig variable.

`PGVECTOR_IVFFLAT_LISTS`

Type: int
Default: 100
Description: IVFFlat index parameter that specifies the number of inverted lists (clusters) to create. A good starting point is rows / 1000 for up to 1M rows and sqrt(rows) for over 1M rows. Only applicable when PGVECTOR_INDEX_METHOD is set to ivfflat.
Persistence: This environment variable is a PersistentConfig variable.

info

For IVFFlat indexes, choosing the right number of lists is crucial for query performance. Too few lists will result in slow queries, while too many will increase index size without significant performance gains.

`PGVECTOR_USE_HALFVEC`

Type: bool
Default: False
Description: Enables the use of halfvec data type instead of vector for storing embeddings. Required when PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH exceeds 2000 dimensions, as the vector type has a 2000-dimension limit.

`PGVECTOR_PGCRYPTO`

Type: bool
Default: False
Description: Enables pgcrypto extension for encrypting sensitive data within PGVector. When enabled, PGVECTOR_PGCRYPTO_KEY must be set.

`PGVECTOR_PGCRYPTO_KEY`

Type: str
Default: None
Description: Specifies the encryption key for pgcrypto when PGVECTOR_PGCRYPTO is enabled. Must be a secure, randomly generated key.

`PGVECTOR_POOL_SIZE`

Type: int
Default: None
Description: Sets the number of connections to maintain in the PGVector database connection pool. If not set, uses SQLAlchemy defaults.

`PGVECTOR_POOL_MAX_OVERFLOW`

Type: int
Default: 0
Description: Specifies the maximum number of connections that can be created beyond PGVECTOR_POOL_SIZE when the pool is exhausted.

`PGVECTOR_POOL_TIMEOUT`

Type: int
Default: 30
Description: Sets the timeout in seconds for acquiring a connection from the PGVector pool.

`PGVECTOR_POOL_RECYCLE`

Type: int
Default: 3600
Description: Specifies the time in seconds after which connections are recycled in the PGVector pool to prevent stale connections.

Qdrant

warning

Qdrant is not actively maintained by the Open WebUI team. It is an addition by the community and is maintained by the community. If you want to use Qdrant, be careful when upgrading Open WebUI (crate backups and snapshots for rollbacks) in case internal changes in Open WebUI lead to breakage.

`QDRANT_API_KEY`

Type: str
Description: Sets the API key for Qdrant.

`QDRANT_URI`

Type: str
Description: Sets the URI for Qdrant.

`QDRANT_ON_DISK`

Type: bool
Default: False
Description: Enable the usage of memmap(also known as on-disk) storage

`QDRANT_PREFER_GRPC`

Type: bool
Default: False
Description: Use gPRC interface whenever possible.

info

If set to True, and QDRANT_URI points to a self-hosted server with TLS enabled and certificate signed by a private CA, set the environment variable GRPC_DEFAULT_SSL_ROOTS_FILE_PATH to the path of your PEM-encoded CA certificates file. See the gRPC Core Docs for more information.

`QDRANT_GRPC_PORT`

Type: int
Default: 6334
Description: Sets the gRPC port number for Qdrant.

`QDRANT_TIMEOUT`

Type: int
Default: 5
Description: Sets the timeout in seconds for all requests made to the Qdrant server, helping to prevent long-running queries from stalling the application.

`QDRANT_HNSW_M`

Type: int
Default: 16
Description: Controls the HNSW (Hierarchical Navigable Small World) index construction. In standard mode, this sets the m parameter. In multi-tenancy mode, this value is used for the payload_m parameter to build indexes on the payload, as the global m is disabled for performance, following Qdrant best practices.

`ENABLE_QDRANT_MULTITENANCY_MODE`

Type: bool
Default: True
Description: Enables multitenancy pattern for Qdrant collections management, which significantly reduces RAM usage and computational overhead by consolidating similar vector data structures. Recommend turn on

info

This will disconect all Qdrant collections created in the previous pattern, which is non-multitenancy. Go to Admin Settings > Documents > Reindex Knowledge Base to migrate existing knowledges.

The Qdrant collections created in the previous pattern will still consume resources.

Currently, there is no button in the UI to only reset the vector DB. If you want to migrate knowledge to multitenancy:

Remove all collections with the open_webui-knowledge prefix (or open_webui prefix to remove all collections related to Open WebUI) using the native Qdrant client
Go to Admin Settings > Documents > Reindex Knowledge Base to migrate existing knowledge base

Reindex Knowledge Base will ONLY migrate the knowledge base

danger

If you decide to use the multitenancy pattern as your default and you don't need to migrate old knowledge, go to Admin Settings > Documents to reset vector and knowledge, which will delete all collections with the open_webui prefix and all stored knowledge.

warning

The mapping of multitenancy relies on current Open WebUI naming conventions for collection names.

If you use Multitenancy Mode, you should always check for any changes to the collection names and data mapping before upgrading, and upgrade carefully (snapshots and backups for rollbacks)!

`QDRANT_COLLECTION_PREFIX`

Type: str
Default: open-webui
Description: Sets the prefix for Qdrant collection names. Useful for namespacing or isolating collections, especially in multitenancy mode. Changing this value will cause the application to use a different set of collections in Qdrant. Existing collections with a different prefix will not be affected.

Pinecone

When using Pinecone as the vector store, the following environment variables are used to control its behavior. Make sure to set these variables in your .env file or deployment environment.

`PINECONE_API_KEY`

Type: str
Default: None
Description: Sets the API key used to authenticate with the Pinecone service.

`PINECONE_ENVIRONMENT`

Type: str
Default: None
Description: Specifies the Pinecone environment to connect to (e.g., us-west1-gcp, gcp-starter, etc.).

`PINECONE_INDEX_NAME`

Type: str
Default: open-webui-index
Description: Defines the name of the Pinecone index that will be used to store and query vector embeddings.

`PINECONE_DIMENSION`

Type: int
Default: 1536
Description: The dimensionality of the vector embeddings. Must match the dimension expected by the index (commonly 768, 1024, 1536, or 3072 based on model used).

`PINECONE_METRIC`

Type: str
Default: cosine
Options: cosine, dotproduct, euclidean
Description: Specifies the similarity metric to use for vector comparisons within the Pinecone index.

`PINECONE_CLOUD`

Type: str
Default: aws
Options: aws, gcp, azure
Description: Specifies the cloud provider where the Pinecone index is hosted.

Weaviate

info

Self-Hosted and Cloud Deployments

Open WebUI uses connect_to_custom for Weaviate connections, which supports both locally hosted and remote Weaviate instances. This is essential for self-hosted deployments where HTTP and gRPC endpoints may be on different ingresses or hostnames, which is common in container orchestration platforms like Kubernetes or Azure Container Apps.

`WEAVIATE_HTTP_HOST`

Type: str
Default: Empty string (' ')
Description: Specifies the hostname of the Weaviate server for HTTP connections. For self-hosted deployments, this is typically your Weaviate HTTP endpoint hostname.

`WEAVIATE_GRPC_HOST`

Type: str
Default: Empty string (' ')
Description: Specifies the hostname of the Weaviate server for gRPC connections. This can be different from WEAVIATE_HTTP_HOST when HTTP and gRPC are served on separate ingresses, which is common in container orchestration environments.

`WEAVIATE_HTTP_PORT`

Type: int
Default: 8080
Description: Specifies the HTTP port for connecting to the Weaviate server.

`WEAVIATE_GRPC_PORT`

Type: int
Default: 50051
Description: Specifies the gRPC port for connecting to the Weaviate server.

`WEAVIATE_HTTP_SECURE`

Type: bool
Default: False
Description: Enables HTTPS for HTTP connections to the Weaviate server. Set to true when connecting to a Weaviate instance with TLS enabled on the HTTP endpoint.

`WEAVIATE_GRPC_SECURE`

Type: bool
Default: False
Description: Enables TLS for gRPC connections to the Weaviate server. Set to true when connecting to a Weaviate instance with TLS enabled on the gRPC endpoint.

`WEAVIATE_API_KEY`

Type: str
Default: None
Description: Sets the API key for authenticating with Weaviate server.

`WEAVIATE_SKIP_INIT_CHECKS`

Type: bool
Default: False
Description: Skips Weaviate initialization checks when connecting. This can be useful in certain network configurations where the checks may fail but the connection itself works.

Oracle 23ai Vector Search (oracle23ai)

`ORACLE_DB_USE_WALLET`

Type: bool
Default: false
Description: Determines the connection method to the Oracle Database.
- Set to false for direct connections (e.g., to Oracle Database 23ai Free or DBCS instances) using host, port, and service name in ORACLE_DB_DSN.
- Set to true for wallet-based connections (e.g., to Oracle Autonomous Database (ADW/ATP)). When true, ORACLE_WALLET_DIR and ORACLE_WALLET_PASSWORD must also be configured.

`ORACLE_DB_USER`

Type: str
Default: DEMOUSER
Description: Specifies the username used to connect to the Oracle Database.

`ORACLE_DB_PASSWORD`

Type: str
Default: Welcome123456
Description: Specifies the password for the ORACLE_DB_USER.

`ORACLE_DB_DSN`

Type: str
Default: localhost:1521/FREEPDB1
Description: Defines the Data Source Name for the Oracle Database connection.
- If ORACLE_DB_USE_WALLET is false, this should be in the format hostname:port/service_name (e.g., localhost:1521/FREEPDB1).
- If ORACLE_DB_USE_WALLET is true, this can be a TNS alias (e.g., medium for ADW/ATP), or a full connection string.

`ORACLE_WALLET_DIR`

Type: str
Default: Empty string (' ')
Description: Required when ORACLE_DB_USE_WALLET is true. Specifies the absolute path to the directory containing the Oracle Cloud Wallet files (e.g., cwallet.sso, sqlnet.ora, tnsnames.ora).

`ORACLE_WALLET_PASSWORD`

Type: str
Default: Empty string (' ')
Description: Required when ORACLE_DB_USE_WALLET is true. Specifies the password for the Oracle Cloud Wallet.

`ORACLE_VECTOR_LENGTH`

Type: int
Default: 768
Description: Sets the expected dimension or length of the vector embeddings stored in the Oracle Database. This must match the embedding model used.

`ORACLE_DB_POOL_MIN`

Type: int
Default: 2
Description: The minimum number of connections to maintain in the Oracle Database connection pool.

`ORACLE_DB_POOL_MAX`

Type: int
Default: 10
Description: The maximum number of connections allowed in the Oracle Database connection pool.

`ORACLE_DB_POOL_INCREMENT`

Type: int
Default: 1
Description: The number of connections to create when the pool needs to grow.

S3 Vector Bucket

When using S3 Vector Bucket as the vector store, the following environment variables are used to control its behavior. Make sure to set these variables in your .env file or deployment environment.

info

Note: this configuration assumes that AWS credentials will be available to your Open WebUI environment. This could be through environment variables like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or through IAM role permissions.

`S3_VECTOR_BUCKET_NAME`

Type: str
Description: Specifies the name of the S3 Vector Bucket to store vectors in.

`S3_VECTOR_REGION`

Type: str
Description: Specifies the AWS region where the S3 Vector Bucket is hosted.

RAG Content Extraction Engine

`CONTENT_EXTRACTION_ENGINE`

Type: str
Options:
- Leave empty to use default
- external - Use external loader
- tika - Use a local Apache Tika server
- docling - Use Docling engine
- document_intelligence - Use Document Intelligence engine
- mistral_ocr - Use Mistral OCR engine
- mineru
Description: Sets the content extraction engine to use for document ingestion.
Persistence: This environment variable is a PersistentConfig variable.

`MISTRAL_OCR_API_KEY`

Type: str
Default: None
Description: Specifies the Mistral OCR API key to use.
Persistence: This environment variable is a PersistentConfig variable.

`MISTRAL_OCR_API_BASE_URL`

Type: str
Default: https://api.mistral.ai/v1
Description: Configures custom Mistral OCR API endpoints for flexible deployment options, allowing users to point to self-hosted or alternative Mistral OCR instances.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_DOCUMENT_LOADER_URL`

Type: str
Default: None
Description: Sets the URL for the external document loader service.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_DOCUMENT_LOADER_API_KEY`

Type: str
Default: None
Description: Sets the API key for authenticating with the external document loader service.
Persistence: This environment variable is a PersistentConfig variable.

`TIKA_SERVER_URL`

Type: str
Default: http://localhost:9998
Description: Sets the URL for the Apache Tika server.
Persistence: This environment variable is a PersistentConfig variable.

`DOCLING_SERVER_URL`

Type: str
Default: http://docling:5001
Description: Specifies the URL for the Docling server. Requires Docling version 2.0.0 or later for full compatibility with the new parameter-based configuration system.
Persistence: This environment variable is a PersistentConfig variable.

warning

Docling 2.0.0+ Required

The Docling integration has been refactored to use server-side parameter passing. If you are using Docling:

Upgrade to Docling server version 2.0.0 or later
Migrate all individual DOCLING_* configuration variables to the DOCLING_PARAMS JSON object
Remove all deprecated DOCLING_* environment variables from your configuration
Add DOCLING_API_KEY if your server requires authentication

The old individual environment variables (DOCLING_OCR_ENGINE, DOCLING_OCR_LANG, etc.) are no longer supported and will be ignored.

`DOCLING_API_KEY`

Type: str
Default: None
Description: Sets the API key for authenticating with the Docling server. Required when the Docling server has authentication enabled.
Persistence: This environment variable is a PersistentConfig variable.

`DOCLING_PARAMS`

Type: str (JSON)
Default: {}
Description: Specifies all Docling processing parameters in JSON format. This is the primary configuration method for Docling processing options. All previously individual Docling settings are now configured through this single JSON object.

Supported Parameters:
- do_ocr (bool): Enable OCR processing.
- force_ocr (bool): Force OCR even when text layer exists.
- ocr_engine (str): OCR engine to use. Options: tesseract, easyocr, ocrmac, rapidocr, tesserocr.
- ocr_lang (list[str]): OCR language codes. Note: Format depends on engine (e.g., ["eng", "fra"] for Tesseract; ["en", "fr"] for EasyOCR).
- pdf_backend (str): PDF processing backend. Options: dlparse_v1, dlparse_v2, dlparse_v4, pypdfium2.
- table_mode (str): Table extraction mode. Options: fast, accurate.
- pipeline (str): Processing pipeline to use. Options: fast, standard.
- do_picture_description (bool): Enable image description generation.
- picture_description_mode (str): Mode for picture descriptions. Options: local, api.
- picture_description_local (str): Local model configuration object for picture descriptions.
- picture_description_api (str): API endpoint configuration object for picture descriptions.
- vlm_pipeline_model_api (str): Vision-language model API configuration. (e.g., openai://gpt-4o).
Example:

{
  "do_ocr": true,
  "ocr_engine": "tesseract",
  "ocr_lang": ["eng", "fra", "deu", "spa"],
  "force_ocr": false,
  "pdf_backend": "dlparse_v4",
  "table_mode": "accurate",
  "do_picture_description": true,
  "picture_description_mode": "api",
  "vlm_pipeline_model_api": "openai://gpt-4o"
}

tip

dlparse vs dbparse: Note that the backend names use dlparse (Deep Learning Parse), not dbparse. For modern Docling (v2+), dlparse_v4 is generally recommended for the best balance of features.

Persistence: This environment variable is a PersistentConfig variable.

info

Migration from Individual Docling Variables

If you were previously using individual DOCLING_* environment variables (such as DOCLING_OCR_ENGINE, DOCLING_OCR_LANG, etc.), these are now deprecated. You must migrate to using DOCLING_PARAMS as a single JSON configuration object.

Example Migration:

# Old configuration (deprecated)
DOCLING_OCR_ENGINE=tesseract
DOCLING_OCR_LANG=eng,fra
DOCLING_DO_OCR=true

# New configuration (required)
DOCLING_PARAMS='{"do_ocr": true, "ocr_engine": "tesseract", "ocr_lang": "eng,fra"}'

warning

When setting this environment variable in a .env file, ensure proper JSON formatting and escape quotes as needed:

DOCLING_PARAMS="{\"do_ocr\": true, \"ocr_engine\": \"tesseract\", \"ocr_lang\": \"eng,fra,deu,spa\"}"

`MINERU_API_TIMEOUT`

Type: str
Default: 300
Description: Sets the timeout in seconds for MinerU API requests during document processing.
Persistence: This environment variable is a PersistentConfig variable.

Retrieval Augmented Generation (RAG)

Core Configuration

`RAG_EMBEDDING_ENGINE`

Type: str
Options:
- Leave empty for Default (SentenceTransformers) - Uses SentenceTransformers for embeddings.
- ollama - Uses the Ollama API for embeddings.
- openai - Uses the OpenAI API for embeddings.
- azure_openai - Uses Azure OpenAI Services for embeddings.
Description: Selects an embedding engine to use for RAG.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_EMBEDDING_MODEL`

Type: str
Default: sentence-transformers/all-MiniLM-L6-v2
Description: Sets a model for embeddings. Locally, a Sentence-Transformer model is used.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_TOP_K`

Type: int
Default: 3
Description: Sets the default number of results to consider for the embedding when using RAG.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_TOP_K_RERANKER`

Type: int
Default: 3
Description: Sets the default number of results to consider for the reranker when using RAG.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_RELEVANCE_THRESHOLD`

Type: float
Default: 0.0
Description: Sets the relevance threshold to consider for documents when used with reranking.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_RAG_HYBRID_SEARCH`

Type: bool
Default: False
Description: Enables the use of ensemble search with BM25 + ChromaDB, with reranking using sentence_transformers models. When enabled, this applies to both the standard RAG retrieval pipeline and the native knowledge tools used in agentic mode.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_HYBRID_BM25_WEIGHT`

Type: float
Default: 0.5
Description: Sets the weight given to the keyword search (BM25) during hybrid search. 1 means only keyword search, 0 means only vector search.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_RAG_HYBRID_SEARCH_ENRICHED_TEXTS`

Type: bool
Default: False
Description: Enhances BM25 hybrid search by enriching indexed text with document metadata including filenames, titles, sections, and snippets. This improves keyword recall for metadata-based queries, allowing searches to match on document names and structural elements in addition to content.
Persistence: This environment variable is a PersistentConfig variable.

info

Enabling this feature increases the text volume indexed by BM25, which may impact storage requirements and indexing performance. However, it significantly improves search results when users query based on document names, titles, or structural elements rather than just content.

`RAG_TEMPLATE`

Type: str
Default: The value of DEFAULT_RAG_TEMPLATE environment variable.

DEFAULT_RAG_TEMPLATE:

### Task:
Respond to the user query using the provided context, incorporating inline citations in the format [id] **only when the <source> tag includes an explicit id attribute** (e.g., <source id="1">).

### Guidelines:
- If you don't know the answer, clearly state that.
- If uncertain, ask the user for clarification.
- Respond in the same language as the user's query.
- If the context is unreadable or of poor quality, inform the user and provide the best possible answer.
- If the answer isn't present in the context but you possess the knowledge, explain this to the user and provide the answer using your own understanding.
- **Only include inline citations using [id] (e.g., [1], [2]) when the <source> tag includes an id attribute.**
- Do not cite if the <source> tag does not contain an id attribute.
- Do not use XML tags in your response.
- Ensure citations are concise and directly related to the information provided.

### Example of Citation:
If the user asks about a specific topic and the information is found in a source with a provided id attribute, the response should include the citation like in the following example:
* "According to the study, the proposed method increases efficiency by 20% [1]."

### Output:
Provide a clear and direct response to the user's query, including inline citations in the format [id] only when the <source> tag with id attribute is present in the context.

<context>
{{CONTEXT}}
</context>

<user_query>
{{QUERY}}
</user_query>

Description: Template to use when injecting RAG documents into chat completion.
Persistence: This environment variable is a PersistentConfig variable.

Document Processing

`CHUNK_SIZE`

Type: int
Default: 1000
Description: Sets the document chunk size for embeddings.
Persistence: This environment variable is a PersistentConfig variable.

`CHUNK_OVERLAP`

Type: int
Default: 100
Description: Specifies how much overlap there should be between chunks.
Persistence: This environment variable is a PersistentConfig variable.

`CHUNK_MIN_SIZE_TARGET`

Type: int
Default: 0
Description: Chunks smaller than this threshold will be intelligently merged with neighboring chunks when possible. This helps prevent tiny, low-quality fragments that can hurt retrieval performance and waste embedding resources. This feature only works when ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER is enabled. Set to 0 to disable merging. For more information on the benefits and configuration, see the RAG guide.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_TEXT_SPLITTER`

Type: str
Options:
- character
- token
Default: character
Description: Sets the text splitter for RAG models. Use character for RecursiveCharacterTextSplitter or token for TokenTextSplitter (Tiktoken-based).
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER`

Type: bool
Default: True
Description: Enables markdown header text splitting as a preprocessing step before character or token splitting. When enabled, documents are first split by markdown headers (h1-h6), then the resulting chunks are further processed by the configured text splitter (RAG_TEXT_SPLITTER). This helps preserve document structure and context across chunks.
Persistence: This environment variable is a PersistentConfig variable.

info

Migration from markdown_header TEXT_SPLITTER

The markdown_header option has been removed from RAG_TEXT_SPLITTER. Markdown header splitting is now a preprocessing step controlled by ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER. If you were using RAG_TEXT_SPLITTER=markdown_header, switch to character or token and ensure ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER is enabled (it is enabled by default).

`TIKTOKEN_CACHE_DIR`

Type: str
Default: {CACHE_DIR}/tiktoken
Description: Sets the directory for TikToken cache.

`TIKTOKEN_ENCODING_NAME`

Type: str
Default: cl100k_base
Description: Sets the encoding name for TikToken.
Persistence: This environment variable is a PersistentConfig variable.

`PDF_EXTRACT_IMAGES`

Type: bool
Default: False
Description: Extracts images from PDFs using OCR when loading documents.
Persistence: This environment variable is a PersistentConfig variable.

`PDF_LOADER_MODE`

Type: str
Options:
- page - Creates one document per page (default).
- single - Combines all pages into one document for better chunking across page boundaries.
Default: page
Description: Controls how PDFs are loaded and split into documents when using the default content extraction engine (PyPDFLoader). Page mode creates one document per page, while single mode combines all pages into one document, which can improve chunking quality when content spans across page boundaries. This setting has no effect when using external content extraction engines like Tika, Docling, Document Intelligence, MinerU, or Mistral OCR, as those engines have their own document handling logic.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_FILE_MAX_SIZE`

Type: int
Description: Sets the maximum size of a file in megabytes that can be uploaded for document ingestion.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_FILE_MAX_COUNT`

Type: int
Description: Sets the maximum number of files that can be uploaded at once for document ingestion.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_ALLOWED_FILE_EXTENSIONS`

Type: list of str
Default: [] (which means all supported file types are allowed)
Description: Specifies which file extensions are permitted for upload.

["pdf,docx,txt"]

Persistence: This environment variable is a PersistentConfig variable.

info

When configuring RAG_FILE_MAX_SIZE and RAG_FILE_MAX_COUNT, ensure that the values are reasonable to prevent excessive file uploads and potential performance issues.

Embedding Engine Configuration

General Embedding Settings

`RAG_EMBEDDING_BATCH_SIZE`

Type: int
Default: 1
Description: Controls how many text chunks are embedded in a single API request when using external embedding providers (Ollama, OpenAI, or Azure OpenAI). Higher values (20-100+; max 16000 (not recommended)) may process documents faster by sending less, but larger API requests. Some external APIs do not support batching or sending more than 1 chunk per request. In such casey you must leave this at 1. Default is 1 (safest option if the API does not support batching / more than 1 chunk per request). This setting only applies to external embedding engines, not the default SentenceTransformers engine.
Persistence: This environment variable is a PersistentConfig variable.

info

Check if your API and embedding model supports batched processing. Only increase this variable's value if it does - otherwise you might run into unexpected issues.

`ENABLE_ASYNC_EMBEDDING`

Type: bool
Default: true
Description: Runs embedding tasks asynchronously (parallelized) for maximum performance. Only works for Ollama, OpenAI and Azure OpenAI, does not affect sentence transformer setups.
Persistence: This environment variable is a PersistentConfig variable.

tip

It may be needed to increase the value of THREAD_POOL_SIZE if many other users are simultaneously using your Open WebUI instance while having async embeddings turned on to prevent

warning

Enabling this will potentially send thousands of requests per minute. If you are embedding locally, ensure that you can handle this amount of requests, otherwise turn this off to return to sequential embedding (slower but will always work). If you are embedding externally via API, ensure your rate limits are high enough to handle parallel embedding. (Usually, OpenAI can handle thousands of embedding requests per minute, even on the lowest API tier).

`RAG_EMBEDDING_CONCURRENT_REQUESTS`

Type: int
Default: 0
Description: Limits the number of concurrent embedding API requests when async embedding is enabled. Uses an asyncio semaphore to throttle parallel requests. Set to 0 for unlimited concurrency (default behavior), or set to a positive integer to cap simultaneous requests. Useful for respecting rate limits on external embedding APIs or reducing load on local embedding servers.
Persistence: This environment variable is a PersistentConfig variable.

tip

If you are hitting rate limits from your embedding provider (e.g., 429 errors), set this to a value that keeps you within your API tier's rate limit (e.g., 5 or 10). This is especially helpful when uploading large documents that generate many embedding batches.

`RAG_EMBEDDING_TIMEOUT`

Type: int (seconds)
Default: None (no timeout)
Description: Sets an optional timeout in seconds for embedding operations during document upload. When set, embedding requests that exceed this duration will be aborted with a timeout error. When unset (default), embedding operations run without a time limit. This setting is primarily relevant for deployments using the default SentenceTransformers embedding engine, where embeddings run locally and can take longer on slower hardware. External embedding engines (Ollama, OpenAI, Azure OpenAI) have their own timeout mechanisms and are generally not affected by this setting.

info

This variable was introduced alongside a fix for uvicorn worker death during document uploads. Previously, local embedding operations could block the worker thread long enough to trigger uvicorn's health check timeout (default: 5 seconds), causing the worker process to be killed. The underlying fix uses run_coroutine_threadsafe to keep the main event loop responsive to health checks regardless of this timeout setting. The timeout is purely a safety net for aborting abnormally long embedding operations — it does not affect worker health check behavior.

`RAG_EMBEDDING_CONTENT_PREFIX`

Type: str
Default: None
Description: Sets the prefix string prepended to document content before generating embeddings. Some embedding models (e.g., nomic-embed-text) require task-specific prefixes to differentiate between content being stored vs. queries being searched. For nomic-embed-text, set this to search_document: . Only needed if your embedding model's documentation specifies a content/document prefix.

`RAG_EMBEDDING_QUERY_PREFIX`

Type: str
Default: None
Description: Sets the prefix string prepended to user queries before generating embeddings for retrieval. This is the counterpart to RAG_EMBEDDING_CONTENT_PREFIX. For nomic-embed-text, set this to search_query: . Only needed if your embedding model's documentation specifies a query prefix.

`RAG_EMBEDDING_PREFIX_FIELD_NAME`

Type: str
Default: None
Description: Specifies the JSON field name used to pass the prefix to the embedding API request body. When set along with a prefix value, the prefix is sent as a separate field in the API request rather than being prepended to the text. Required for embedding APIs that accept the prefix as a dedicated parameter instead of inline text.

OpenAI Embeddings

`RAG_OPENAI_API_BASE_URL`

Type: str
Default: ${OPENAI_API_BASE_URL}
Description: Sets the OpenAI base API URL to use for RAG embeddings.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_OPENAI_API_KEY`

Type: str
Default: ${OPENAI_API_KEY}
Description: Sets the OpenAI API key to use for RAG embeddings.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_EMBEDDING_OPENAI_BATCH_SIZE`

Type: int
Default: 1
Description: Sets the batch size for OpenAI embeddings.

Azure OpenAI Embeddings

`RAG_AZURE_OPENAI_BASE_URL`

Type: str
Default: None
Description: Sets the base URL for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Should be in the format https://{your-resource-name}.openai.azure.com.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_AZURE_OPENAI_API_KEY`

Type: str
Default: None
Description: Sets the API key for Azure OpenAI Services when using Azure OpenAI for RAG embeddings.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_AZURE_OPENAI_API_VERSION`

Type: str
Default: None
Description: Sets the API version for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Common values include 2023-05-15, 2023-12-01-preview, or 2024-02-01.
Persistence: This environment variable is a PersistentConfig variable.

Ollama Embeddings

`RAG_OLLAMA_BASE_URL`

Type: str
Description: Sets the base URL for Ollama API used in RAG models.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_OLLAMA_API_KEY`

Type: str
Description: Sets the API key for Ollama API used in RAG models.
Persistence: This environment variable is a PersistentConfig variable.

Reranking

`RAG_RERANKING_ENGINE`

Type: str
Options: external, or empty for local Sentence-Transformer CrossEncoder
Default: Empty string (local reranking)
Description: Specifies the reranking engine to use. Set to external to use an external reranker API (requires RAG_EXTERNAL_RERANKER_URL). Leave empty to use a local Sentence-Transformer CrossEncoder model.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_RERANKING_MODEL`

Type: str
Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used.
Persistence: This environment variable is a PersistentConfig variable.

`SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION`

Type: bool
Default: True
Description: When enabled (default), applies sigmoid normalization to local CrossEncoder reranking scores to ensure they fall within the 0-1 range. This allows the relevance threshold setting to work correctly with models like MS MARCO that output raw logits.

`RAG_EXTERNAL_RERANKER_TIMEOUT`

Type: str
Default: Empty string (' ')
Description: Sets the timeout in seconds for external reranker API requests during RAG document retrieval. Leave empty to use default timeout behavior.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_EXTERNAL_RERANKER_URL`

Type: str
Default: Empty string (' ')
Description: Sets the full URL for the external reranking API.
Persistence: This environment variable is a PersistentConfig variable.

warning

You MUST provide the full URL, including the endpoint path (e.g., https://api.yourprovider.com/v1/rerank). The system does not automatically append /v1/rerank or any other path to the base URL you provide.

`RAG_EXTERNAL_RERANKER_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for the external reranking API.
Persistence: This environment variable is a PersistentConfig variable.

Query Generation

`ENABLE_RETRIEVAL_QUERY_GENERATION`

Type: bool
Default: True
Description: Enables or disables retrieval query generation.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_QUERIES_CACHE`

Type: bool
Default: False
Description: Enables request-scoped caching of LLM-generated search queries. When enabled, queries generated for web search are cached and automatically reused for file/knowledge base retrieval within the same request. This eliminates duplicate LLM calls when both web search and RAG are active, reducing token usage and latency while maintaining search quality. It is highly recommended to enable this especially in larger setups.

`QUERY_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: The value of DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE environment variable.

DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE:

### Task:
Analyze the chat history to determine the necessity of generating search queries, in the given language. By default, **prioritize generating 1-3 broad and relevant search queries** unless it is absolutely certain that no additional information is required. The aim is to retrieve comprehensive, updated, and valuable information even with minimal uncertainty. If no search is unequivocally needed, return an empty list.

### Guidelines:
- Respond **EXCLUSIVELY** with a JSON object. Any form of extra commentary, explanation, or additional text is strictly prohibited.
- When generating search queries, respond in the format: { "queries": ["query1", "query2"] }, ensuring each query is distinct, concise, and relevant to the topic.
- If and only if it is entirely certain that no useful results can be retrieved by a search, return: { "queries": [] }.
- Err on the side of suggesting search queries if there is **any chance** they might provide useful or updated information.
- Be concise and focused on composing high-quality search queries, avoiding unnecessary elaboration, commentary, or assumptions.
- Today's date is: {{CURRENT_DATE}}.
- Always prioritize providing actionable and broad queries that maximize informational coverage.

### Output:
Strictly return in JSON format:
{
  "queries": ["query1", "query2"]
}

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>

Description: Sets the prompt template for query generation.
Persistence: This environment variable is a PersistentConfig variable.

Document Intelligence (Azure)

`DOCUMENT_INTELLIGENCE_ENDPOINT`

Type: str
Default: None
Description: Specifies the endpoint for document intelligence.
Persistence: This environment variable is a PersistentConfig variable.

`DOCUMENT_INTELLIGENCE_KEY`

Type: str
Default: None
Description: Specifies the key for document intelligence.
Persistence: This environment variable is a PersistentConfig variable.

`DOCUMENT_INTELLIGENCE_MODEL`

Type: str
Default: None
Description: Specifies the model for document intelligence.
Persistence: This environment variable is a PersistentConfig variable.

Advanced Settings

`BYPASS_EMBEDDING_AND_RETRIEVAL`

Type: bool
Default: False
Description: Bypasses the embedding and retrieval process.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_FULL_CONTEXT`

Type: bool
Default: False
Description: Specifies whether to use the full context for RAG.
Persistence: This environment variable is a PersistentConfig variable.

`RAG_SYSTEM_CONTEXT`

Type: bool
Default: False
Description: When enabled, injects RAG context into the system message instead of the user message. This is highly recommended for optimizing performance when using models that support KV prefix caching or Prompt Caching. This includes local engines (like Ollama, llama.cpp, or vLLM) and cloud providers / Model-as-a-Service providers (like OpenAI and Vertex AI). By placing the context in the system message, it remains at a stable position at the start of the conversation, allowing the cache to persist across multiple turns. When disabled (default), context is injected into the user message, which shifts position each turn and invalidates the cache.

`ENABLE_RAG_LOCAL_WEB_FETCH`

Type: bool
Default: False
Description: Controls whether RAG web fetch operations can access URLs that resolve to private/local network IP addresses.
Persistence: This environment variable is a PersistentConfig variable.

When disabled (default), Open WebUI blocks web fetch requests to URLs that resolve to private IP addresses, including:

IPv4 private ranges (10.x.x.x, 172.16.x.x-172.31.x.x, 192.168.x.x, 127.x.x.x)
IPv6 private ranges

This is a Server-Side Request Forgery (SSRF) protection. Without this safeguard, a malicious user could provide URLs that appear external but resolve to internal addresses, potentially exposing internal services, cloud metadata endpoints, or other sensitive resources.

warning

Only enable this setting if you need to fetch content from internal network resources (e.g., an internal wiki or intranet) and you trust all users with access to your Open WebUI instance. Enabling this in a multi-tenant or public-facing deployment introduces significant security risk.

Google Drive

`ENABLE_GOOGLE_DRIVE_INTEGRATION`

Type: bool
Default: False
Description: Enables or disables Google Drive integration. If set to true, and GOOGLE_DRIVE_CLIENT_ID & GOOGLE_DRIVE_API_KEY are both configured, Google Drive will appear as an upload option in the chat UI.
Persistence: This environment variable is a PersistentConfig variable.

info

When enabling GOOGLE_DRIVE_INTEGRATION, ensure that you have configured GOOGLE_DRIVE_CLIENT_ID and GOOGLE_DRIVE_API_KEY correctly, and have reviewed Google's terms of service and usage guidelines.

`GOOGLE_DRIVE_CLIENT_ID`

Type: str
Description: Sets the client ID for Google Drive (client must be configured with Drive API and Picker API enabled).
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_DRIVE_API_KEY`

Type: str
Description: Sets the API key for Google Drive integration.
Persistence: This environment variable is a PersistentConfig variable.

OneDrive

info

For a step-by-step setup guide, check out our tutorial: Configuring OneDrive & SharePoint Integration.

`ENABLE_ONEDRIVE_INTEGRATION`

Type: bool
Default: False
Description: Enables or disables the Microsoft OneDrive integration feature globally.
Persistence: This environment variable is a PersistentConfig variable.

warning

Configuring OneDrive integration is a multi-step process that requires creating and correctly configuring an Azure App Registration. The authentication flow also depends on a browser pop-up window. Please ensure that your browser's pop-up blocker is disabled for your Open WebUI domain to allow the authentication and file selection window to appear.

`ENABLE_ONEDRIVE_PERSONAL`

Type: bool
Default: True
Description: Controls whether the "Personal OneDrive" option appears in the attachment menu. Requires ONEDRIVE_PERSONAL_CLIENT_ID to be configured.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_ONEDRIVE_BUSINESS`

Type: bool
Default: True
Description: Controls whether the "Work/School OneDrive" option appears in the attachment menu. Requires ONEDRIVE_CLIENT_ID to be configured.
Persistence: This environment variable is a PersistentConfig variable.

`ONEDRIVE_CLIENT_ID`

Type: str
Default: None
Description: Generic environment variable for the OneDrive Client ID. You should rather use the specific ONEDRIVE_CLIENT_ID_PERSONAL or ONEDRIVE_CLIENT_ID_BUSINESS variables. This exists as a legacy option for backwards compatibility.

`ONEDRIVE_CLIENT_ID_PERSONAL`

Type: str
Default: None
Description: Specifies the Application (client) ID for the Personal OneDrive integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. Do not put the business OneDrive client ID here!

`ONEDRIVE_CLIENT_ID_BUSINESS`

Type: str
Default: None
Description: Specifies the Application (client) ID for the Work/School (Business) OneDrive integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. Do not put the personal OneDrive client ID here!

info

This Client ID (also known as Application ID) is obtained from an Azure App Registration within your Microsoft Entra ID (formerly Azure AD) tenant. When configuring the App Registration in Azure, the Redirect URI must be set to the URL of your Open WebUI instance and configured as a Single-page application (SPA) type for the authentication to succeed.

`ONEDRIVE_SHAREPOINT_URL`

Type: str
Default: None
Description: Specifies the root SharePoint site URL for the work/school integration, e.g., https://companyname.sharepoint.com.
Persistence: This environment variable is a PersistentConfig variable.

info

This variable is essential for the work/school integration. It should point to the root SharePoint site associated with your tenant, enabling access to SharePoint document libraries.

`ONEDRIVE_SHAREPOINT_TENANT_ID`

Type: str
Default: None
Description: Specifies the Directory (tenant) ID for the work/school integration. This is obtained from your business-focused Azure App Registration.
Persistence: This environment variable is a PersistentConfig variable.

info

This Tenant ID (also known as Directory ID) is required for the work/school integration. You can find this value on the main overview page of your Azure App Registration in the Microsoft Entra ID portal.

Web Search

`ENABLE_WEB_SEARCH`

Type: bool
Default: False
Description: Enable web search toggle.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_SEARCH_QUERY_GENERATION`

Type: bool
Default: True
Description: Only used in Default Function Calling mode - If True: An LLM generates optimized, distilled search queries from the conversation context. If False: The user's last message is used verbatim as the web search query
Persistence: This environment variable is a PersistentConfig variable.

`WEB_SEARCH_TRUST_ENV`

Type: bool
Default: False
Description: Enables proxy set by http_proxy and https_proxy during web search content fetching.
Persistence: This environment variable is a PersistentConfig variable.

`WEB_FETCH_FILTER_LIST`

Type: string (comma-separated list)
Default: "" (empty, but default blocklist is always applied)
Description: Configures additional URL filtering rules for web fetch operations to prevent Server-Side Request Forgery (SSRF) attacks. The system includes a default blocklist that protects against access to cloud metadata endpoints (AWS, Google Cloud, Azure, Alibaba Cloud). Entries without a ! prefix are treated as an allow list (only these domains are permitted), while entries with a ! prefix are added to the block list (these domains are always denied). The default blocklist includes !169.254.169.254, !fd00:ec2::254, !metadata.google.internal, !metadata.azure.com, and !100.100.100.200. Custom entries are merged with the default blocklist.

info

Example:

Block additional domains: WEB_FETCH_FILTER_LIST="!internal.company.com,!192.168.1.1" Allow only specific domains: WEB_FETCH_FILTER_LIST="example.com,trusted-site.org"

`WEB_SEARCH_DOMAIN_FILTER_LIST`

Type: list of str
Default: []
Description: Comma-separated list of domains to filter web search results. Domains prefixed with ! are blocked; domains without prefix create an allowlist (only those domains permitted).
Example: wikipedia.org,github.com,!malicious-site.com
Persistence: This environment variable is a PersistentConfig variable.

`WEB_SEARCH_RESULT_COUNT`

Type: int
Default: 3
Description: Maximum number of search results to crawl.
Persistence: This environment variable is a PersistentConfig variable.

`WEB_SEARCH_CONCURRENT_REQUESTS`

Type: int
Default: 0
Description: Limits the number of concurrent search requests to the search engine provider. Set to 0 for unlimited concurrency (default). Set to 1 for sequential execution to prevent rate limiting errors (e.g., Brave Free Tier).
Persistence: This environment variable is a PersistentConfig variable.

`WEB_FETCH_MAX_CONTENT_LENGTH`

Type: int
Default: None (no limit)
Description: Maximum number of characters to return from fetched URLs. When set, content exceeding this limit is truncated. Previously hardcoded at 50,000 characters. Leave empty or unset to return full content without truncation. Useful for controlling context window usage with large web pages.
Persistence: This environment variable is a PersistentConfig variable.

`WEB_LOADER_CONCURRENT_REQUESTS`

Type: int
Default: 10
Description: Specifies the number of concurrent requests used by the web loader to fetch content from web pages returned by search results. This directly impacts how many pages can be crawled simultaneously.
Persistence: This environment variable is a PersistentConfig variable.

info

"WEB_LOADER_CONCURRENT_REQUESTS" was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". The variable "WEB_SEARCH_CONCURRENT_REQUESTS" has been repurposed to control the concurrency of the search engine requests (see above). To control the web loader concurrency (fetching content from results), you MUST use "WEB_LOADER_CONCURRENT_REQUESTS".

`WEB_SEARCH_ENGINE`

Type: str
Options:
- searxng - Uses the SearXNG search engine.
- google_pse - Uses the Google Programmable Search Engine.
- brave - Uses the Brave search engine.
- kagi - Uses the Kagi search engine.
- mojeek - Uses the Mojeek search engine.
- bocha - Uses the Bocha search engine.
- serpstack - Uses the Serpstack search engine.
- serper - Uses the Serper search engine.
- serply - Uses the Serply search engine.
- searchapi - Uses the SearchAPI search engine.
- serpapi - Uses the SerpApi search engine.
- duckduckgo - Uses the DuckDuckGo search engine.
- tavily - Uses the Tavily search engine.
- jina - Uses the Jina search engine.
- bing - Uses the Bing search engine.
- exa - Uses the Exa search engine.
- perplexity - Uses the Perplexity API to access perplexity's AI models. Calls their AI models, which execute a search and also return a full response.
- perplexity_search - Uses the Perplexity Search API search engine. In contrast to the perplexity option, this uses Perplexity's web search API for searching the web and retrieving results.
- sougou - Uses the Sougou search engine.
- ollama_cloud - Uses the Ollama Cloud search engine.
- azure_ai_search
- yacy
- yandex - Uses the Yandex Search API.
- youcom - Uses the You.com YDC Index API for web search.
Persistence: This environment variable is a PersistentConfig variable.

`DDGS_BACKEND`

Type: str
Default: auto
Options: auto (Random), bing, brave, duckduckgo, google, grokipedia, mojeek, wikipedia, yahoo, yandex.
Description: Specifies the backend to be used by the DDGS engine.
Persistence: This environment variable is a PersistentConfig variable. It can be configured in the Admin Panel > Settings > Web Search > DDGS Backend when DDGS is selected as the search engine.

`BYPASS_WEB_SEARCH_EMBEDDING_AND_RETRIEVAL`

Type: bool
Default: False
Description: Bypasses the web search embedding and retrieval process.
Persistence: This environment variable is a PersistentConfig variable.

`BYPASS_WEB_SEARCH_WEB_LOADER`

Type: bool
Default: False
Description: Bypasses the web loader when performing web search. When enabled, only snippets from the search engine are used, and the full page content is not fetched.
Persistence: This environment variable is a PersistentConfig variable.

`SEARXNG_QUERY_URL`

Type: str
Description: The SearXNG search API URL supporting JSON output. <query> is replaced with the search query. Example: http://searxng.local/search?q=<query>
Persistence: This environment variable is a PersistentConfig variable.

`SEARXNG_LANGUAGE`

Type: str
Default: all
Description: This variable is used in the request to searxng as the "search language" (arguement "language").
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_PSE_API_KEY`

Type: str
Description: Sets the API key for the Google Programmable Search Engine (PSE) service.
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_PSE_ENGINE_ID`

Type: str
Description: The engine ID for the Google Programmable Search Engine (PSE) service.
Persistence: This environment variable is a PersistentConfig variable.

`BRAVE_SEARCH_API_KEY`

Type: str
Description: Sets the API key for the Brave Search API.
Persistence: This environment variable is a PersistentConfig variable.

info

Brave's free tier enforces a rate limit of 1 request per second. Open WebUI automatically retries requests that receive HTTP 429 rate limit errors after a 1-second delay. For free tier users, set WEB_SEARCH_CONCURRENT_REQUESTS to 1 to ensure sequential request processing. See the Brave web search documentation for more details.

`KAGI_SEARCH_API_KEY`

Type: str
Description: Sets the API key for Kagi Search API.
Persistence: This environment variable is a PersistentConfig variable.

`MOJEEK_SEARCH_API_KEY`

Type: str
Description: Sets the API key for Mojeek Search API.
Persistence: This environment variable is a PersistentConfig variable.

`SERPSTACK_API_KEY`

Type: str
Description: Sets the API key for Serpstack search API.
Persistence: This environment variable is a PersistentConfig variable.

`SERPSTACK_HTTPS`

Type: bool
Default: True
Description: Configures the use of HTTPS for Serpstack requests. Free tier requests are restricted to HTTP only.
Persistence: This environment variable is a PersistentConfig variable.

`SERPER_API_KEY`

Type: str
Description: Sets the API key for Serper search API.
Persistence: This environment variable is a PersistentConfig variable.

`SERPLY_API_KEY`

Type: str
Description: Sets the API key for Serply search API.
Persistence: This environment variable is a PersistentConfig variable.

`SEARCHAPI_API_KEY`

Type: str
Description: Sets the API key for SearchAPI.
Persistence: This environment variable is a PersistentConfig variable.

`SEARCHAPI_ENGINE`

Type: str
Description: Sets the SearchAPI engine.
Persistence: This environment variable is a PersistentConfig variable.

`TAVILY_API_KEY`

Type: str
Description: Sets the API key for Tavily search API.
Persistence: This environment variable is a PersistentConfig variable.

`JINA_API_KEY`

Type: str
Description: Sets the API key for Jina.
Persistence: This environment variable is a PersistentConfig variable.

`JINA_API_BASE_URL`

Type: str
Default: https://s.jina.ai/
Description: Sets the Base URL for Jina Search API. Useful for specifying custom or regional endpoints (e.g., https://eu-s-beta.jina.ai/).
Persistence: This environment variable is a PersistentConfig variable. It can be configured in the Admin Panel > Settings > Web Search > Jina API Base URL.

`BING_SEARCH_V7_ENDPOINT`

Type: str
Description: Sets the endpoint for Bing Search API.
Persistence: This environment variable is a PersistentConfig variable.

`BING_SEARCH_V7_SUBSCRIPTION_KEY`

Type: str
Default: https://api.bing.microsoft.com/v7.0/search
Description: Sets the subscription key for Bing Search API.
Persistence: This environment variable is a PersistentConfig variable.

`BOCHA_SEARCH_API_KEY`

Type: str
Default: None
Description: Sets the API key for Bocha Search API.
Persistence: This environment variable is a PersistentConfig variable.

`EXA_API_KEY`

Type: str
Default: None
Description: Sets the API key for Exa search API.
Persistence: This environment variable is a PersistentConfig variable.

`SERPAPI_API_KEY`

Type: str
Default: None
Description: Sets the API key for SerpAPI.
Persistence: This environment variable is a PersistentConfig variable.

`SERPAPI_ENGINE`

Type: str
Default: None
Description: Specifies the search engine to use for SerpAPI.
Persistence: This environment variable is a PersistentConfig variable.

`AZURE_AI_SEARCH_API_KEY`

Type: str
Default: None
Description: API key (query key or admin key) for authenticating with Azure AI Search service. Required for using Azure AI Search as a web search provider.
Persistence: This environment variable is a PersistentConfig variable.

`AZURE_AI_SEARCH_ENDPOINT`

Type: str
Default: None
Description: Azure Search service endpoint URL. Specifies which Azure Search service instance to connect to.
Example: https://myservice.search.windows.net, https://company-search.search.windows.net
Persistence: This environment variable is a PersistentConfig variable.

`AZURE_AI_SEARCH_INDEX_NAME`

Type: str
Default: None
Description: Name of the search index to query within your Azure Search service. Different indexes can contain different types of searchable content.
Example: my-search-index, documents-index, knowledge-base
Persistence: This environment variable is a PersistentConfig variable.

`SOUGOU_API_SID`

Type: str
Default: None
Description: Sets the Sogou API SID.
Persistence: This environment variable is a PersistentConfig variable.

`SOUGOU_API_SK`

Type: str
Default: None
Description: Sets the Sogou API SK.
Persistence: This environment variable is a PersistentConfig variable.

`OLLAMA_CLOUD_WEB_SEARCH_API_KEY`

Type: str
Default: None
Description: Sets the Ollama Cloud Web Search API Key.
Persistence: This environment variable is a PersistentConfig variable.

`TAVILY_EXTRACT_DEPTH`

Type: str
Default: basic
Description: Specifies the extract depth for Tavily search results.
Persistence: This environment variable is a PersistentConfig variable.

`YACY_QUERY_URL`

Type: str
Default: Empty string (' ')
Description: Sets the query URL for YaCy search engine integration. Should point to a YaCy instance's search API endpoint.
Persistence: This environment variable is a PersistentConfig variable.

`YACY_USERNAME`

Type: str
Default: Empty string (' ')
Description: Specifies the username for authenticated access to YaCy search engine.
Persistence: This environment variable is a PersistentConfig variable.

`YACY_PASSWORD`

Type: str
Default: Empty string (' ')
Description: Specifies the password for authenticated access to YaCy search engine.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_WEB_SEARCH_URL`

Type: str
Default: Empty string (' ')
Description: Specifies the URL of an external web search service API endpoint for custom search integrations.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_WEB_SEARCH_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for authenticating with the external web search service.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_WEB_LOADER_URL`

Type: str
Default: Empty string (' ')
Description: Specifies the URL of an external web content loader service for fetching and processing web pages.
Persistence: This environment variable is a PersistentConfig variable.

`EXTERNAL_WEB_LOADER_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for authenticating with the external web loader service.
Persistence: This environment variable is a PersistentConfig variable.

`YANDEX_WEB_SEARCH_URL`

Type: str
Default: https://searchapi.api.cloud.yandex.net/v2/web/search
Description: Specifies the URL of the Yandex Web Search service API endpoint.
Persistence: This environment variable is a PersistentConfig variable.

`YANDEX_WEB_SEARCH_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for authenticating with the Yandex Web Search service.
Persistence: This environment variable is a PersistentConfig variable.

`YANDEX_WEB_SEARCH_CONFIG`

Type: str
Default: Empty string (' ')
Description: Optional JSON configuration string for Yandex Web Search. Can be used to set parameters like searchType or region as per the Yandex API documentation.
Persistence: This environment variable is a PersistentConfig variable.

`PERPLEXITY_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for Perplexity API.
Persistence: This environment variable is a PersistentConfig variable.

`PERPLEXITY_SEARCH_API_URL`

Type: str
Default: https://api.perplexity.ai/search
Description: Configures the API endpoint for Perplexity Search. Allows using custom or self-hosted Perplexity-compatible API endpoints (such as LiteLLM's /search endpoint) instead of the hardcoded default for the official Perplexity API. This enables flexibility in routing search requests to alternative providers or internal proxies. Note: If using LiteLLM, append the specific provider name to the URL path.
Example: http://my-litellm-server.com/search/perplexity-search
Persistence: This environment variable is a PersistentConfig variable.

`PERPLEXITY_MODEL`

Type: str
Default: sonar
Description: Specifies the Perplexity AI model to use for search queries when using Perplexity as the web search engine.
Persistence: This environment variable is a PersistentConfig variable.

info

Perplexity is different from perplexity_search. If you use perplexity_search, this variable is not relevant to you.

`PERPLEXITY_SEARCH_CONTEXT_USAGE`

Type: str
Default: medium
Description: Controls the amount of search context used by Perplexity AI. Options typically include low, medium, high.
Persistence: This environment variable is a PersistentConfig variable.

info

Perplexity is different from perplexity_search. If you use perplexity, this variable is not relevant to you.

`YOUCOM_API_KEY`

Type: str
Default: Empty string (' ')
Description: Sets the API key for You.com YDC Index API web search. Required when WEB_SEARCH_ENGINE is set to youcom. Obtain an API key from You.com API.
Persistence: This environment variable is a PersistentConfig variable.

Web Loader Configuration

`WEB_LOADER_ENGINE`

Type: str
Default: (empty)
Description: Specifies the loader to use for retrieving and processing web content.
Options:
- safe_web (default) - Uses internal fetching with enhanced error handling.
- playwright - Uses Playwright for rendering pages with JavaScript support.
- firecrawl - Uses Firecrawl service.
- tavily - Uses Tavily service.
- external - Uses an external web loader API.
Persistence: This environment variable is a PersistentConfig variable.

info

When using playwright, you have two options:

If PLAYWRIGHT_WS_URI is not set, Playwright with Chromium dependencies will be automatically installed in the Open WebUI container on launch.
If PLAYWRIGHT_WS_URI is set, Open WebUI will connect to a remote browser instance instead of installing dependencies locally.

`PLAYWRIGHT_WS_URL`

Type: str
Default: None
Description: Specifies the WebSocket URI of a remote Playwright browser instance. When set, Open WebUI will use this remote browser instead of installing browser dependencies locally. This is particularly useful in containerized environments where you want to keep the Open WebUI container lightweight and separate browser concerns. Example: ws://playwright:3000
Persistence: This environment variable is a PersistentConfig variable.

tip

Using a remote Playwright browser via PLAYWRIGHT_WS_URL can be beneficial for:

Reducing the size of the Open WebUI container
Using a different browser other than the default Chromium
Connecting to a non-headless (GUI) browser

`FIRECRAWL_API_BASE_URL`

Type: str
Default: https://api.firecrawl.dev
Description: Sets the base URL for Firecrawl API.
Persistence: This environment variable is a PersistentConfig variable.

`FIRECRAWL_API_KEY`

Type: str
Default: None
Description: Sets the API key for Firecrawl API.
Persistence: This environment variable is a PersistentConfig variable.

`FIRECRAWL_TIMEOUT`

Type: int
Default: None
Description: Specifies the timeout in milliseconds for Firecrawl requests. If not set, the default Firecrawl timeout is used.
Persistence: This environment variable is a PersistentConfig variable. It can be configured in the Admin Panel > Settings > Web Search > Firecrawl Timeout.

`PLAYWRIGHT_TIMEOUT`

Type: int
Default: Empty string (' '), since None is set as default.
Description: Specifies the timeout for Playwright requests.
Persistence: This environment variable is a PersistentConfig variable.

`WEB_LOADER_TIMEOUT`

Type: float
Default: Empty string (' '), since None is set as default.
Description: Specifies the request timeout in seconds for the SafeWebBaseLoader when scraping web pages. Without this setting, web scraping operations can hang indefinitely on slow or unresponsive pages. Recommended values are 10–30 seconds depending on your network conditions.
Persistence: This environment variable is a PersistentConfig variable.

warning

This timeout only applies when WEB_LOADER_ENGINE is set to safe_web or left empty (the default). It has no effect on Playwright or Firecrawl loader engines, which have their own timeout configurations (PLAYWRIGHT_TIMEOUT and Firecrawl's internal settings respectively).

YouTube Loader

`YOUTUBE_LOADER_PROXY_URL`

Type: str
Description: Sets the proxy URL for YouTube loader.
Persistence: This environment variable is a PersistentConfig variable.

`YOUTUBE_LOADER_LANGUAGE`

Type: str
Default: en
Description: Comma-separated list of language codes to try when fetching YouTube video transcriptions, in priority order.
Example: If set to es,de, Spanish transcriptions will be attempted first, then German if Spanish was not available, and lastly English.

note

Note: If none of the specified languages are available and en was not in your list, the system will automatically try English as a final fallback.

Persistence: This environment variable is a PersistentConfig variable.

Audio

Whisper Speech-to-Text (Local)

`WHISPER_MODEL`

Type: str
Default: base
Description: Sets the Whisper model to use for Speech-to-Text. The backend used is faster_whisper with quantization to int8.
Persistence: This environment variable is a PersistentConfig variable.

`WHISPER_MODEL_DIR`

Type: str
Default: ${DATA_DIR}/cache/whisper/models
Description: Specifies the directory to store Whisper model files.

`WHISPER_COMPUTE_TYPE`

Type: str
Default: int8 (CPU), float16 (CUDA)
Description: Sets the compute type for Whisper model inference. Defaults to int8 for CPU and float16 for CUDA (with fallback to int8/int8_float16).

`WHISPER_VAD_FILTER`

Type: bool
Default: False
Description: Specifies whether to apply a Voice Activity Detection (VAD) filter to Whisper Speech-to-Text.

`WHISPER_MODEL_AUTO_UPDATE`

Type: bool
Default: False
Description: Toggles automatic update of the Whisper model.

`WHISPER_LANGUAGE`

Type: str
Default: None
Description: Specifies the ISO 639-1 language Whisper uses for STT (ISO 639-2 for Hawaiian and Cantonese). Whisper predicts the language by default.

`WHISPER_MULTILINGUAL`

Type: bool
Default: False
Description: Toggles whether to use the multilingual Whisper model. When set to False, the system will use the English-only model for better performance in English-centric tasks. When True, it supports multiple languages.

Speech-to-Text (OpenAI)

`AUDIO_STT_ENGINE`

Type: str
Options:
- "" (empty string) - Uses the built-in local Whisper engine for Speech-to-Text. This runs Whisper on the backend server.
- openai - Uses an OpenAI-compatible API for Speech-to-Text.
- deepgram - Uses Deepgram engine for Speech-to-Text.
- azure - Uses Azure Cognitive Services for Speech-to-Text.
- mistral - Uses Mistral API for Speech-to-Text.
Description: Specifies the Speech-to-Text engine to use. When left as an empty string (the default), the backend runs a local Whisper instance. Note: The "Web API" option seen in User Settings is a frontend-only setting that uses the browser's built-in speech recognition and does not call this backend endpoint at all.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_MODEL`

Type: str
Default: whisper-1
Description: Specifies the Speech-to-Text model to use for OpenAI-compatible endpoints.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_OPENAI_API_BASE_URL`

Type: str
Default: ${OPENAI_API_BASE_URL}
Description: Sets the OpenAI-compatible base URL to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_OPENAI_API_KEY`

Type: str
Default: ${OPENAI_API_KEY}
Description: Sets the OpenAI API key to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

Speech-to-Text (Azure)

`AUDIO_STT_AZURE_API_KEY`

Type: str
Default: None
Description: Specifies the Azure API key to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_AZURE_REGION`

Type: str
Default: None
Description: Specifies the Azure region to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_AZURE_LOCALES`

Type: str
Default: None
Description: Specifies the locales to use for Azure Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_AZURE_BASE_URL`

Type: str
Default: None
Description: Specifies a custom Azure base URL for Speech-to-Text. Use this if you have a custom Azure endpoint.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_AZURE_MAX_SPEAKERS`

Type: int
Default: 3
Description: Sets the maximum number of speakers for Azure Speech-to-Text diarization.
Persistence: This environment variable is a PersistentConfig variable.

Speech-to-Text (Deepgram)

`DEEPGRAM_API_KEY`

Type: str
Default: None
Description: Specifies the Deepgram API key to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

Speech-to-Text (Mistral)

`AUDIO_STT_MISTRAL_API_KEY`

Type: str
Default: None
Description: Specifies the Mistral API key to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_MISTRAL_API_BASE_URL`

Type: str
Default: https://api.mistral.ai/v1
Description: Specifies the Mistral API base URL to use for Speech-to-Text.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_STT_MISTRAL_USE_CHAT_COMPLETIONS`

Type: bool
Default: False
Description: When enabled, uses the chat completions endpoint for Mistral Speech-to-Text instead of the dedicated transcription endpoint.
Persistence: This environment variable is a PersistentConfig variable.

Speech-to-Text (General)

`AUDIO_STT_SUPPORTED_CONTENT_TYPES`

Type: str
Default: None
Description: Comma-separated list of supported audio MIME types for Speech-to-Text (e.g., audio/wav,audio/mpeg,video/*). Leave empty to use defaults.
Persistence: This environment variable is a PersistentConfig variable.

Text-to-Speech

`AUDIO_TTS_API_KEY`

Type: str
Description: Sets the API key for Text-to-Speech.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_ENGINE`

Type: str
Options:
- "" (empty string) - Disables backend TTS. When empty, TTS requests do not reach the backend. All TTS is handled client-side using the browser's Web Speech API or the user-configurable "Browser Kokoro" option in User Settings.
- openai - Uses an OpenAI-compatible API for Text-to-Speech.
- elevenlabs - Uses ElevenLabs engine for Text-to-Speech.
- azure - Uses Azure Cognitive Services for Text-to-Speech.
- transformers - Uses a local SentenceTransformers-based model for Text-to-Speech (runs on the backend).
Description: Specifies the Text-to-Speech engine to use on the backend. When left as an empty string (the default), no backend TTS service is configured, and audio playback relies entirely on the user's browser capabilities or frontend options like "Browser Kokoro".
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_MODEL`

Type: str
Default: tts-1
Description: Specifies the OpenAI text-to-speech model to use.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_VOICE`

Type: str
Default: alloy
Description: Sets the OpenAI text-to-speech voice to use.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_SPLIT_ON`

Type: str
Default: punctuation
Description: Sets the OpenAI text-to-speech split on to use.
Persistence: This environment variable is a PersistentConfig variable.

Azure Text-to-Speech

`AUDIO_TTS_AZURE_SPEECH_REGION`

Type: str
Description: Sets the region for Azure Text to Speech.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_AZURE_SPEECH_OUTPUT_FORMAT`

Type: str
Default: audio-24khz-160kbitrate-mono-mp3
Description: Sets the output format for Azure Text to Speech.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_AZURE_SPEECH_BASE_URL`

Type: str
Default: None
Description: Specifies a custom Azure Speech base URL for Text-to-Speech. Use this if you have a custom Azure endpoint.
Persistence: This environment variable is a PersistentConfig variable.

Voice Mode

`VOICE_MODE_PROMPT_TEMPLATE`

Type: str
Default: The value of DEFAULT_VOICE_MODE_PROMPT_TEMPLATE environment variable.
Description: Configures a custom system prompt for voice mode interactions. Allows administrators to control how the AI responds in voice conversations (style, length, tone). Leave empty to use the default prompt optimized for voice conversations, or provide custom instructions to tailor the voice assistant's behavior.
Persistence: This environment variable is a PersistentConfig variable.

OpenAI Text-to-Speech

`AUDIO_TTS_OPENAI_API_BASE_URL`

Type: str
Default: ${OPENAI_API_BASE_URL}
Description: Sets the OpenAI-compatible base URL to use for text-to-speech.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_OPENAI_API_KEY`

Type: str
Default: ${OPENAI_API_KEY}
Description: Sets the API key to use for text-to-speech.
Persistence: This environment variable is a PersistentConfig variable.

`AUDIO_TTS_OPENAI_PARAMS`

Type: str (JSON)
Default: {}
Description: Additional parameters for OpenAI-compatible TTS API in JSON format. Allows customization of API-specific settings.
Example: {"speed": 1.0}
Persistence: This environment variable is a PersistentConfig variable.

Elevenlabs Text-to-Speech

`ELEVENLABS_API_BASE_URL`

Type: str
Default: https://api.elevenlabs.io
Description: Configures custom ElevenLabs API endpoints, enabling support for EU residency API requirements and other regional deployments.
Persistence: This environment variable is a PersistentConfig variable.

Image Generation

General Settings

`ENABLE_IMAGE_GENERATION`

Type: bool
Default: False
Description: Enables or disables image generation features.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_IMAGE_PROMPT_GENERATION`

Type: bool
Default: True
Description: Enables or disables automatic enhancement of user prompts for better image generation results.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE`

Type: str
Default: None
Description: Specifies the template to use for generating image prompts.
Persistence: This environment variable is a PersistentConfig variable.

DEFAULT_IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate a detailed prompt for an image generation task based on the given language and context. Describe the image as if you were explaining it to someone who cannot see it. Include relevant details, colors, shapes, and any other important elements.

### Guidelines:
- Be descriptive and detailed, focusing on the most important aspects of the image.
- Avoid making assumptions or adding information not present in the image.
- Use the chat's primary language; default to English if multilingual.
- If the image is too complex, focus on the most prominent elements.

### Output:
Strictly return in JSON format:
{
    "prompt": "Your detailed description here."
}

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>

Image Creation

`IMAGE_GENERATION_ENGINE`

Type: str
Options:
- openai - Uses OpenAI DALL-E for image generation.
- comfyui - Uses ComfyUI engine for image generation.
- automatic1111 - Uses AUTOMATIC1111 engine for image generation.
- gemini - Uses Gemini for image generation.
Default: openai
Description: Specifies the engine to use for image generation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_GENERATION_MODEL`

Type: str
Default: ``
Description: Default model to use for image generation (e.g., dall-e-3, gemini-2.0-flash-exp).
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_SIZE`

Type: str
Default: 512x512
Description: Sets the default output dimensions for generated images in WIDTHxHEIGHT format (e.g., 1024x1024). Set to auto to let the model determine the appropriate size (only supported by models matching IMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN).
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN`

Type: str
Default: ^gpt-image
Description: A regex pattern to match model names that support IMAGE_SIZE = "auto". When a model matches this pattern, the auto size option becomes available, allowing the model to determine the appropriate output dimensions. By default, only models starting with gpt-image (e.g., gpt-image-1) are matched.

`IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERN`

Type: str
Default: ^gpt-image
Description: A regex pattern to match model names that return image URLs directly instead of base64-encoded data. Models matching this pattern will not include response_format: b64_json in API requests. By default, only models starting with gpt-image are matched. For other models, Open WebUI requests base64 responses and handles the conversion internally.

`IMAGE_STEPS`

Type: int
Default: 50
Description: Sets the default iteration steps for image generation. Used for ComfyUI and AUTOMATIC1111 engines.
Persistence: This environment variable is a PersistentConfig variable.

Image Editing

`ENABLE_IMAGE_EDIT`

Type: boolean
Default: true
Description: When disabled, Image Editing will not be used and instead, images will be created only using the image generation engine.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_EDIT_ENGINE`

Type: str
Options:
- openai - Uses OpenAI DALL-E for image editing.
- gemini - Uses Gemini for image editing.
- comfyui - Uses ComfyUI engine for image editing.
Default: openai
Description: Configures the engine used for image editing operations, enabling modification of existing images using text prompts.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_EDIT_MODEL`

Type: str
Default: ``
Description: Specifies the model to use for image editing operations within the selected engine (e.g., dall-e-2, gemini-2.5-flash).
Persistence: This environment variable is a PersistentConfig variable.

`IMAGE_EDIT_SIZE`

Type: str
Default: ``
Description: Defines the output dimensions for edited images in WIDTHxHEIGHT format (e.g., 1024x1024). Leave empty to preserve original dimensions.
Persistence: This environment variable is a PersistentConfig variable.

OpenAI DALL-E

Image Generation

`IMAGES_OPENAI_API_BASE_URL`

Type: str
Default: ${OPENAI_API_BASE_URL}
Description: Sets the OpenAI-compatible base URL to use for DALL-E image generation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_OPENAI_API_VERSION`

Type: str
Default: ${OPENAI_API_VERSION}
Description: Optional setting. If provided it sets the api-version query parameter when calling the image generation endpoint. Required for Azure OpenAI deployments.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_OPENAI_API_KEY`

Type: str
Default: ${OPENAI_API_KEY}
Description: Sets the API key to use for DALL-E image generation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_OPENAI_API_PARAMS`

Type: str (JSON)
Default: {}
Description: Additional parameters for OpenAI image generation API in JSON format. Allows customization of API-specific settings such as quality parameters for DALL-E models (e.g., {"quality": "hd"} for dall-e-3).
Example: {"quality": "hd", "style": "vivid"}
Persistence: This environment variable is a PersistentConfig variable.

Image Editing

`IMAGES_EDIT_OPENAI_API_BASE_URL`

Type: str
Default: ${OPENAI_API_BASE_URL}
Description: Configures the OpenAI API base URL specifically for image editing operations, allowing separate endpoints from image generation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_OPENAI_API_VERSION`

Type: str
Default: ``
Description: Specifies the OpenAI API version for image editing, enabling support for Azure OpenAI deployments with versioned endpoints.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_OPENAI_API_KEY`

Type: str
Default: ${OPENAI_API_KEY}
Description: Provides authentication for OpenAI image editing API requests, with support for separate keys from image generation.
Persistence: This environment variable is a PersistentConfig variable.

Gemini

tip

For a detailed setup guide and example configuration, please refer to the Gemini Image Generation Guide.

Image Generation

`IMAGES_GEMINI_API_BASE_URL`

Type: str
Default: ${GEMINI_API_BASE_URL}
Description: Specifies the URL to Gemini's image generation API.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_GEMINI_API_KEY`

Type: str
Default: ${GEMINI_API_KEY}
Description: Sets the Gemini API key for image generation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_GEMINI_ENDPOINT_METHOD`

Type: str
Options:
- predict - Uses the predict endpoint (default for Imagen models).
- generateContent - Uses the generateContent endpoint (for Gemini 2.5 Flash and newer models).
Default: ``
Description: Specifies the Gemini API endpoint method for image generation, supporting both legacy Imagen models and newer Gemini models with image generation capabilities.
Persistence: This environment variable is a PersistentConfig variable.

Image Editing

`IMAGES_EDIT_GEMINI_API_BASE_URL`

Type: str
Default: ${GEMINI_API_BASE_URL}
Description: Configures the Gemini API base URL for image editing operations with Gemini models.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_GEMINI_API_KEY`

Type: str
Default: ${GEMINI_API_KEY}
Description: Provides authentication for Gemini image editing API requests.
Persistence: This environment variable is a PersistentConfig variable.

ComfyUI

Image Generation

`COMFYUI_BASE_URL`

Type: str
Default: ``
Description: Specifies the URL to the ComfyUI image generation API (e.g., http://127.0.0.1:8188).
Persistence: This environment variable is a PersistentConfig variable.

`COMFYUI_API_KEY`

Type: str
Default: ``
Description: Sets the API key for ComfyUI authentication.
Persistence: This environment variable is a PersistentConfig variable.

`COMFYUI_WORKFLOW`

Type: str (JSON)
Default:

{
  "3": {
    "inputs": {
      "seed": 0,
      "steps": 20,
      "cfg": 8,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    },
    "class_type": "KSampler",
    "_meta": {
      "title": "KSampler"
    }
  },
  "4": {
    "inputs": {
      "ckpt_name": "model.safetensors"
    },
    "class_type": "CheckpointLoaderSimple",
    "_meta": {
      "title": "Load Checkpoint"
    }
  },
  "5": {
    "inputs": {
      "width": 512,
      "height": 512,
      "batch_size": 1
    },
    "class_type": "EmptyLatentImage",
    "_meta": {
      "title": "Empty Latent Image"
    }
  },
  "6": {
    "inputs": {
      "text": "Prompt",
      "clip": ["4", 1]
    },
    "class_type": "CLIPTextEncode",
    "_meta": {
      "title": "CLIP Text Encode (Prompt)"
    }
  },
  "7": {
    "inputs": {
      "text": "",
      "clip": ["4", 1]
    },
    "class_type": "CLIPTextEncode",
    "_meta": {
      "title": "CLIP Text Encode (Prompt)"
    }
  },
  "8": {
    "inputs": {
      "samples": ["3", 0],
      "vae": ["4", 2]
    },
    "class_type": "VAEDecode",
    "_meta": {
      "title": "VAE Decode"
    }
  },
  "9": {
    "inputs": {
      "filename_prefix": "ComfyUI",
      "images": ["8", 0]
    },
    "class_type": "SaveImage",
    "_meta": {
      "title": "Save Image"
    }
  }
}

Description: Defines the ComfyUI workflow configuration in JSON format. Export from ComfyUI using "Save (API Format)" to ensure compatibility.
Persistence: This environment variable is a PersistentConfig variable.

`COMFYUI_WORKFLOW_NODES`

Type: list[dict]
Default: []
Description: Specifies the ComfyUI workflow node mappings for image generation, defining which nodes handle prompt, model, dimensions, and other parameters. Configured automatically via the admin UI.
Persistence: This environment variable is a PersistentConfig variable.

Image Editing

`IMAGES_EDIT_COMFYUI_BASE_URL`

Type: str
Default: ``
Description: Configures the ComfyUI base URL for image editing operations, enabling self-hosted ComfyUI workflows for image manipulation.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_COMFYUI_API_KEY`

Type: str
Default: ``
Description: Provides authentication for ComfyUI image editing API requests when the ComfyUI instance requires API key authentication.
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_COMFYUI_WORKFLOW`

Type: str (JSON)
Default: ``
Description: Defines the ComfyUI workflow configuration in JSON format for image editing operations. Must include nodes for image input, prompt, and output. Export from ComfyUI using "Save (API Format)".
Persistence: This environment variable is a PersistentConfig variable.

`IMAGES_EDIT_COMFYUI_WORKFLOW_NODES`

Type: list[dict]
Default: []
Description: Specifies the ComfyUI workflow node mappings for image editing, defining which nodes handle image input, prompt, model, dimensions, and other parameters. Configured automatically via the admin UI.
Persistence: This environment variable is a PersistentConfig variable.

AUTOMATIC1111

`AUTOMATIC1111_BASE_URL`

Type: str
Default: ``
Description: Specifies the URL to AUTOMATIC1111's Stable Diffusion API (e.g., http://127.0.0.1:7860).
Persistence: This environment variable is a PersistentConfig variable.

`AUTOMATIC1111_API_AUTH`

Type: str
Default: ``
Description: Sets the AUTOMATIC1111 API authentication credentials if required.
Persistence: This environment variable is a PersistentConfig variable.

`AUTOMATIC1111_PARAMS`

Type: str (JSON)
Default: {}
Description: Additional parameters in JSON format to pass to AUTOMATIC1111 API requests (e.g., {"cfg_scale": 7, "sampler_name": "Euler a", "scheduler": "normal"}).
Persistence: This environment variable is a PersistentConfig variable.

OAuth

info

You can only configure one OAUTH provider at a time. You cannot have two or more OAUTH providers configured simultaneously.

`ENABLE_OAUTH_SIGNUP`

Type: bool
Default: False
Description: Enables account creation when signing up via OAuth. Distinct from ENABLE_SIGNUP.
Persistence: This environment variable is a PersistentConfig variable.

danger

ENABLE_LOGIN_FORM must be set to False when ENABLE_OAUTH_SIGNUP is set to True. Failure to do so will result in the inability to login.

`ENABLE_OAUTH_PERSISTENT_CONFIG`

Type: bool
Default: True
Description: Controls whether OAuth-related settings are persisted in the database after the first launch.

info

By default, OAuth configurations are stored in the database and managed via the Admin Panel after the initial setup. Set this variable to False to force Open WebUI to always read OAuth settings from the environment variables on every restart. This is ideal for environments using GitOps or immutable infrastructure where configuration is managed exclusively through external files (e.g., Docker Compose, Kubernetes ConfigMaps).

`OAUTH_SUB_CLAIM`

Type: str
Default: None
Description: Overrides the default claim used to identify a user's unique ID (sub) from the OAuth/OIDC provider's user info response. By default, Open WebUI attempts to infer this from the provider's configuration. This variable allows you to explicitly specify which claim to use. For example, if your identity provider uses 'employee_id' as the unique identifier, you would set this variable to 'employee_id'.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_MERGE_ACCOUNTS_BY_EMAIL`

Type: bool
Default: False
Description: If enabled, merges OAuth accounts with existing accounts using the same email address. This is considered unsafe as not all OAuth providers will verify email addresses and can lead to potential account takeovers.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_OAUTH_WITHOUT_EMAIL`

Type: bool
Default: False
Description: Enables authentication with OpenID Connect (OIDC) providers that do not support or expose an email scope. When enabled, Open WebUI will create and manage user accounts without requiring an email address from the OAuth provider.
Persistence: This environment variable is a PersistentConfig variable.

warning

Use with Caution

Enabling this option bypasses email-based user identification, which is the standard method for uniquely identifying users across authentication systems. When enabled:

User accounts will be created using the sub claim (or the claim specified in OAUTH_SUB_CLAIM) as the primary identifier
Email-based features such as password recovery, email notifications, and account merging via OAUTH_MERGE_ACCOUNTS_BY_EMAIL will not function properly
Ensure your OIDC provider's sub claim is stable and unique to prevent authentication conflicts

Only enable this if your identity provider does not support email scope and you have alternative user identification mechanisms in place.

This setting is designed for enterprise environments using identity providers that:

Use employee IDs, usernames, or other non-email identifiers as the primary user claim
Have privacy policies that prevent sharing email addresses via OAuth
Operate in air-gapped or highly restricted networks where email-based services are unavailable

For most standard OAuth providers (Google, Microsoft, GitHub, etc.), this setting should remain False.

`OAUTH_UPDATE_PICTURE_ON_LOGIN`

Type: bool
Default: False
Description: If enabled, updates the local user profile picture with the OAuth-provided picture on login.
Persistence: This environment variable is a PersistentConfig variable.

info

If the OAuth picture claim is disabled by setting OAUTH_PICTURE_CLAIM to '' (empty string), then setting this variable to true will not update the user profile pictures.

`ENABLE_OAUTH_ID_TOKEN_COOKIE`

Type: bool
Default: True
Description: Controls whether the legacy oauth_id_token cookie (unsafe, not recommended, token can go stale/orphaned) is set in the browser upon a successful OAuth login. This is provided for backward compatibility with custom tools or older versions that might rely on scraping this cookie. The new, recommended approach is to use the server-side session management.
Usage: For new and secure deployments, it is recommended to set this to False to minimize the information exposed to the client-side. Keep it as True only if you have integrations that depend on the old cookie-based method.

`ENABLE_OAUTH_TOKEN_EXCHANGE`

Type: bool
Default: False
Description: Enables the OAuth token exchange endpoint, allowing external applications to exchange an OAuth provider's access token for an Open WebUI JWT session token. This enables programmatic authentication for external tools and services that already have OAuth tokens from your identity provider.
Usage: Set to true to enable the token exchange endpoint at /api/v1/oauth/{provider}/token/exchange. When enabled, external applications can POST to this endpoint with an OAuth access token to obtain an Open WebUI session token.

warning

Security Note: This feature should only be enabled when you have external applications that need to authenticate with Open WebUI using OAuth tokens from your identity provider. Ensure proper access controls are in place for any external applications using this endpoint.

Request Example:

curl -X POST "http://localhost:8080/api/v1/oauth/google/token/exchange" \
  -H "Content-Type: application/json" \
  -d '{"token": "ya29.a0AfH6SMB..."}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": 1735682400,
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "profile_image_url": "https://...",
  "permissions": {...}
}

Requirements:

The user must already exist in Open WebUI (they must have signed in via the web interface at least once)
The OAuth provider must be properly configured
The token exchange uses the same user lookup logic as regular OAuth login (by OAuth sub claim first, then by email if OAUTH_MERGE_ACCOUNTS_BY_EMAIL is enabled)

`OAUTH_CLIENT_INFO_ENCRYPTION_KEY`

Type: str
Default: Falls back to the value of WEBUI_SECRET_KEY.
Description: Specifies the secret key used to encrypt and decrypt OAuth client tokens stored server-side in the database. This is a critical security component for OAuth client tokens. If not set, it defaults to using the main WEBUI_SECRET_KEY, but it is highly recommended to set it to a unique, securely generated value for production environments. OAUTH_CLIENT_INFO_ENCRYPTION_KEY is used in conjunction with OAuth 2.1 MCP server authentication.

`OAUTH_SESSION_TOKEN_ENCRYPTION_KEY`

Type: str
Default: Falls back to the value of WEBUI_SECRET_KEY.
Description: Specifies the secret key used to encrypt and decrypt OAuth tokens stored server-side in the database. This is a critical security component for protecting user credentials at rest. If not set, it defaults to using the main WEBUI_SECRET_KEY, but it is highly recommended to set it to a unique, securely generated value for production environments.

warning

Required for Multi-Replica Deployments In any production environment running more than one instance of Open WebUI (e.g., Docker Swarm, Kubernetes), this variable MUST be explicitly set to a persistent, shared secret. If left unset, each replica will generate or use a different key, causing session decryption to fail intermittently as user requests are load-balanced across instances.

`OAUTH_MAX_SESSIONS_PER_USER`

Type: int
Default: 10
Description: Maximum number of concurrent OAuth sessions allowed per user per provider. When a user logs in and the number of existing sessions for that user/provider combination meets or exceeds this limit, the oldest sessions are pruned to make room for the new one. This prevents unbounded session growth while allowing multi-device usage (e.g., logging in from a desktop and a mobile device without invalidating either session).

`OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE`

Type: bool
Default: False
Description: Ensures the full OAuth scope is included during refresh token requests instead of relying on provider defaults. When enabled, the configured scope (e.g. MICROSOFT_OAUTH_SCOPE) is passed to the identity provider during token refresh. This is required for providers like Microsoft where missing scopes can cause refresh failures, especially when using custom API scopes.

`WEBUI_AUTH_TRUSTED_EMAIL_HEADER`

Type: str
Description: Defines the trusted request header for authentication. See SSO docs.

`WEBUI_AUTH_TRUSTED_NAME_HEADER`

Type: str
Description: Defines the trusted request header for the username of anyone registering with the WEBUI_AUTH_TRUSTED_EMAIL_HEADER header. See SSO docs.

`WEBUI_AUTH_TRUSTED_GROUPS_HEADER`

Type: str
Description: Defines the trusted request header containing a comma-separated list of group memberships for the user when using trusted header authentication. See SSO docs.

`WEBUI_AUTH_TRUSTED_ROLE_HEADER`

Type: str
Description: Defines the trusted request header that determines the user's role (admin, user, or pending) when using trusted header authentication. When set, the user's role is updated to match the header value on every sign-in. Invalid values are ignored with a warning. See SSO docs.

Google

See https://support.google.com/cloud/answer/6158849?hl=en

info

You must also set OPENID_PROVIDER_URL or otherwise logout may not work.

`GOOGLE_CLIENT_ID`

Type: str
Description: Sets the client ID for Google OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_CLIENT_SECRET`

Type: str
Description: Sets the client secret for Google OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_OAUTH_SCOPE`

Type: str
Default: openid email profile
Description: Sets the scope for Google OAuth authentication.
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_REDIRECT_URI`

Type: str
Default: <backend>/oauth/google/callback
Description: Sets the redirect URI for Google OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`GOOGLE_OAUTH_AUTHORIZE_PARAMS`

Type: str (JSON object)
Default: {}
Description: Adds Google-specific parameters to the OAuth /authorize request. Useful for Google flows that require extra parameters such as prompt, login_hint, or hd.

# Example (.env)
GOOGLE_OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com","hd":"example.com"}

warning

GOOGLE_OAUTH_AUTHORIZE_PARAMS must be valid JSON and must be a JSON object. If parsing fails, Open WebUI ignores it and logs a warning.

Microsoft

See https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app

info

You must also set OPENID_PROVIDER_URL or otherwise logout may not work.

`MICROSOFT_CLIENT_ID`

Type: str
Description: Sets the client ID for Microsoft OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_CLIENT_SECRET`

Type: str
Description: Sets the client secret for Microsoft OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_CLIENT_TENANT_ID`

Type: str
Description: Sets the tenant ID for Microsoft OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_OAUTH_SCOPE`

Type: str
Default: openid email profile
Description: Sets the scope for Microsoft OAuth authentication. This scope is also included in refresh token requests when OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE is enabled, which is required by Azure AD to avoid AADSTS90009 errors. If you use custom API scopes, include them here (e.g., openid email profile offline_access api://<Application ID URI>/<custom_scope>).
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_REDIRECT_URI`

Type: str
Default: <backend>/oauth/microsoft/callback
Description: Sets the redirect URI for Microsoft OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_CLIENT_LOGIN_BASE_URL`

Type: str
Default: https://login.microsoftonline.com
Description: Sets the base login URL for Microsoft OAuth authentication. Allows configuration of alternative login endpoints for government clouds or custom deployments.
Persistence: This environment variable is a PersistentConfig variable.

`MICROSOFT_CLIENT_PICTURE_URL`

Type: str
Default: https://graph.microsoft.com/v1.0/me/photo/$value
Description: Specifies the Microsoft Graph API endpoint for retrieving user profile pictures during OAuth authentication.
Persistence: This environment variable is a PersistentConfig variable.

GitHub

See https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps

info

You must also set OPENID_PROVIDER_URL or otherwise logout may not work.

`GITHUB_CLIENT_ID`

Type: str
Description: Sets the client ID for GitHub OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`GITHUB_CLIENT_SECRET`

Type: str
Description: Sets the client secret for GitHub OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`GITHUB_CLIENT_SCOPE`

Type: str
Default: user:email
Description: Specifies the scope for GitHub OAuth authentication.
Persistence: This environment variable is a PersistentConfig variable.

`GITHUB_CLIENT_REDIRECT_URI`

Type: str
Default: <backend>/oauth/github/callback
Description: Sets the redirect URI for GitHub OAuth.
Persistence: This environment variable is a PersistentConfig variable.

Feishu

See https://open.feishu.cn/document/sso/web-application-sso/login-overview

`FEISHU_CLIENT_ID`

Type: str
Description: Sets the client ID for Feishu OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`FEISHU_CLIENT_SECRET`

Type: str
Description: Sets the client secret for Feishu OAuth.
Persistence: This environment variable is a PersistentConfig variable.

`FEISHU_CLIENT_SCOPE`

Type: str
Default: contact:user.base:readonly
Description: Specifies the scope for Feishu OAuth authentication.
Persistence: This environment variable is a PersistentConfig variable.

`FEISHU_CLIENT_REDIRECT_URI`

Type: str
Description: Sets the redirect URI for Feishu OAuth.
Persistence: This environment variable is a PersistentConfig variable.

OpenID (OIDC)

`OAUTH_CLIENT_ID`

Type: str
Description: Sets the client ID for OIDC.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_CLIENT_SECRET`

Type: str
Description: Sets the client secret for OIDC.
Persistence: This environment variable is a PersistentConfig variable.

`OPENID_PROVIDER_URL`

Type: str
Description: Path to the .well-known/openid-configuration endpoint
Persistence: This environment variable is a PersistentConfig variable.

danger

The environment variable OPENID_PROVIDER_URL MUST be configured, otherwise the logout functionality will not work for most providers. Even when using Microsoft, GitHub or other providers, you MUST set the OPENID_PROVIDER_URL environment variable.

Alternatively, if your provider does not support standard OIDC discovery (e.g., AWS Cognito), you can set OPENID_END_SESSION_ENDPOINT to a custom logout URL instead.

`OPENID_END_SESSION_ENDPOINT`

Type: str
Default: Empty string ("")
Description: Sets a custom end-session (logout) endpoint URL. When configured, Open WebUI will redirect to this URL on logout instead of attempting OIDC discovery via OPENID_PROVIDER_URL. This is useful for OAuth providers that do not support standard OIDC discovery for logout, such as AWS Cognito.
Persistence: This environment variable is a PersistentConfig variable.

`OPENID_REDIRECT_URI`

Type: str
Default: <backend>/oauth/oidc/callback
Description: Sets the redirect URI for OIDC
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_SCOPES`

Type: str
Default: openid email profile
Description: Sets the scope for OIDC authentication. openid and email are required.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_CODE_CHALLENGE_METHOD`

Type: str
Options:
- S256 - Hash code_verifier with SHA-256.
Default: Empty string (' '), since None is set as default.
Description: Specifies the code challenge method for OAuth authentication. Set to S256 when PKCE is required by the provider.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_PROVIDER_NAME`

Type: str
Default: SSO
Description: Sets the name for the OIDC provider.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_USERNAME_CLAIM`

Type: str
Default: name
Description: Set username claim for OpenID.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_EMAIL_CLAIM`

Type: str
Default: email
Description: Set email claim for OpenID.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_PICTURE_CLAIM`

Type: str
Default: picture
Description: Set picture (avatar) claim for OpenID.
Persistence: This environment variable is a PersistentConfig variable.

info

If OAUTH_PICTURE_CLAIM is set to '' (empty string), then the OAuth picture claim is disabled and the user profile pictures will not be saved.

`OAUTH_GROUP_CLAIM`

Type: str
Default: groups
Description: Specifies the group claim for OAuth authentication.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_OAUTH_ROLE_MANAGEMENT`

Type: bool
Default: False
Description: Enables role management for OAuth delegation.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_OAUTH_GROUP_MANAGEMENT`

Type: bool
Default: False
Description: Enables or disables OAuth group management.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_OAUTH_GROUP_CREATION`

Type: bool
Default: False
Description: When enabled, groups from OAuth claims that don't exist in Open WebUI will be automatically created.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_GROUP_DEFAULT_SHARE`

Type: str
Default: true
Options:
- true — Groups created via OAuth will have sharing enabled for anyone.
- members — Groups created via OAuth will only allow sharing with group members.
- false — Groups created via OAuth will have sharing disabled (no one can share).
Description: Controls the default sharing permission for groups that are automatically created via OAuth group management. Only applies when ENABLE_OAUTH_GROUP_CREATION is enabled. Existing groups are not affected by this setting.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_BLOCKED_GROUPS`

Type: str
Default: []
Description: JSON array of group names that are blocked from accessing the application. Users belonging to these groups will be denied access even if they have valid OAuth credentials.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_ROLES_CLAIM`

Type: str
Default: roles
Description: Sets the roles claim to look for in the OIDC token.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_ALLOWED_ROLES`

Type: str
Default: user,admin
Description: Sets the roles that are allowed access to the platform.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_ADMIN_ROLES`

Type: str
Default: admin
Description: Sets the roles that are considered administrators.
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_ROLES_SEPARATOR`

Type: str
Default: ,
Description: Allows custom role separators for for splitting the OAUTH_*_ROLES variables. Meant for OAuth roles that contain commas; useful for roles specified in LDAP syntax or other systems where commas are part of role names. If the claim is a string and contains the separator, it will be also split by that separator.

`OAUTH_GROUPS_SEPARATOR`

Type: str
Default: ;
Description: Specifies the delimiter used to parse multiple group names from the OAuth group claim. This separator is used when the identity provider returns group memberships as a delimited string rather than an array. Useful when integrating with systems that use non-standard separators or when group names themselves contain commas.

`OAUTH_ALLOWED_DOMAINS`

Type: str
Default: *
Description: Specifies the allowed domains for OAuth authentication. (e.g., "example1.com,example2.com").
Persistence: This environment variable is a PersistentConfig variable.

`OAUTH_AUDIENCE`

Type: str
Default: Empty string (' ')
Description: Specifies an audience parameter passed to the OAuth provider's authorization endpoint during login. Some providers (such as Auth0 and Ory) use this value to determine the type of access token returned—without it, providers typically return an opaque token, while with it, they return a JWT that can be decoded and validated. This parameter is not part of the official OAuth/OIDC spec for authorization endpoints but is widely supported by some providers.

info

This is useful when you need a JWT access token for downstream validation or when your OAuth provider requires an audience hint for proper token generation. For Auth0, this is typically your API identifier (e.g., https://your-api.auth0.com/api/v2/). For Ory, specify the resource server you want to access.

`OAUTH_AUTHORIZE_PARAMS`

Type: str (JSON object)
Default: {}
Description: Passes extra parameters directly to the OAuth provider's authorization endpoint during login. Use this when your provider requires custom authorize-time parameters that are not covered by dedicated variables.

Common examples include parameters like prompt, login_hint, domain_hint, resource, audience, or provider-specific flags.

# Example (.env)
OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}

# Example (docker-compose)
environment:
  - OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}

warning

OAUTH_AUTHORIZE_PARAMS must be valid JSON and must be a JSON object (key/value map). If parsing fails, Open WebUI ignores it and logs a warning.

info

If you set both OAUTH_AUDIENCE and OAUTH_AUTHORIZE_PARAMS containing an audience key, the value from OAUTH_AUTHORIZE_PARAMS takes precedence.

`OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE`

Type: bool
Default: False
Description: When enabled, includes the configured OAuth scope in refresh token requests. Some OAuth providers, notably Microsoft Azure AD, require the scope to be explicitly provided when refreshing a token. Without it, Azure AD treats the request as the application requesting a token for itself, resulting in AADSTS90009 errors. Enable this if you encounter token refresh failures with your OAuth provider.
Persistence: This environment variable is a PersistentConfig variable.

info

This setting is compliant with RFC 6749 Section 6, where the scope parameter is optional during refresh token requests. Only enable this for providers that require it, such as certain Azure AD configurations.

LDAP

`ENABLE_LDAP`

Type: bool
Default: False
Description: Enables or disables LDAP authentication.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SERVER_LABEL`

Type: str
Description: Sets the label of the LDAP server.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SERVER_HOST`

Type: str
Default: localhost
Description: Sets the hostname of the LDAP server.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SERVER_PORT`

Type: int
Default: 389
Description: Sets the port number of the LDAP server.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_ATTRIBUTE_FOR_MAIL`

Type: str
Description: Sets the attribute to use as mail for LDAP authentication.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_ATTRIBUTE_FOR_USERNAME`

Type: str
Description: Sets the attribute to use as a username for LDAP authentication.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_APP_DN`

Type: str
Description: Sets the distinguished name for the LDAP application.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_APP_PASSWORD`

Type: str
Description: Sets the password for the LDAP application.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SEARCH_BASE`

Type: str
Description: Sets the base to search for LDAP authentication.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SEARCH_FILTER`

Type: str
Default: None
Description: Sets additional filter conditions for LDAP user search. This filter is appended to the automatically-generated username filter. Open WebUI automatically constructs the username portion of the filter using LDAP_ATTRIBUTE_FOR_USERNAME, so you should not include user placeholders like %(user)s or %s — these are not supported. Use this for additional conditions such as group membership restrictions (e.g., (memberOf=cn=allowed-users,ou=groups,dc=example,dc=com)). Alternative to LDAP_SEARCH_FILTERS.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_SEARCH_FILTERS`

Type: str
Description: Sets additional filter conditions for LDAP user search. This is an alias for LDAP_SEARCH_FILTER. The filter is appended to the automatically-generated username filter — do not include user placeholders like %(user)s or %s.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_USE_TLS`

Type: bool
Default: True
Description: Enables or disables TLS for LDAP connection.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_CA_CERT_FILE`

Type: str
Description: Sets the path to the LDAP CA certificate file.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_VALIDATE_CERT`

Type: bool
Description: Sets whether to validate the LDAP CA certificate.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_CIPHERS`

Type: str
Default: ALL
Description: Sets the ciphers to use for LDAP connection.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_LDAP_GROUP_MANAGEMENT`

Type: bool
Default: False
Description: Enables the group management feature.
Persistence: This environment variable is a PersistentConfig variable.

`ENABLE_LDAP_GROUP_CREATION`

Type: bool
Default: False
Description: If a group from LDAP does not exist in Open WebUI, it will be created automatically.
Persistence: This environment variable is a PersistentConfig variable.

`LDAP_ATTRIBUTE_FOR_GROUPS`

Type: str
Default: memberOf
Description: Specifies the LDAP attribute that contains the user's group memberships. memberOf is a standard attribute for this purpose in Active Directory environments.
Persistence: This environment variable is a PersistentConfig variable.

SCIM

`SCIM_ENABLED`

Type: bool
Default: False
Description: Enables or disables SCIM 2.0 (System for Cross-domain Identity Management) support for automated user and group provisioning from identity providers like Okta, Azure AD, and Google Workspace.
Persistence: This environment variable is a PersistentConfig variable.

`SCIM_TOKEN`

Type: str
Default: ""
Description: Sets the bearer token for SCIM authentication. This token must be provided by identity providers when making SCIM API requests. Generate a secure random token (e.g., using openssl rand -base64 32) and configure it in both Open WebUI and your identity provider.
Persistence: This environment variable is a PersistentConfig variable.

`SCIM_AUTH_PROVIDER`

Type: str
Default: ""
Description: Specifies the OAuth provider name to associate with SCIM externalId values (e.g., microsoft, oidc). When set, SCIM operations store and look up externalId under this provider key in the user's scim JSON field, enabling account linking between SCIM-provisioned identities and OAuth logins. A warning is logged on startup if SCIM is enabled but this variable is not set.

User Permissions

Chat Permissions

`USER_PERMISSIONS_CHAT_CONTROLS`

Type: bool
Default: True
Description: Acts as a master switch to enable or disable the main "Controls" button and panel in the chat interface. If this is set to False, users will not see the Controls button, and the granular permissions below will have no effect.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_VALVES`

Type: bool
Default: True
Description: When USER_PERMISSIONS_CHAT_CONTROLS is enabled, this setting specifically controls the visibility of the "Valves" section within the chat controls panel.

`USER_PERMISSIONS_CHAT_SYSTEM_PROMPT`

Type: bool
Default: True
Description: When USER_PERMISSIONS_CHAT_CONTROLS is enabled, this setting specifically controls the visibility of the customizable "System Prompt" section within the chat controls panel, folders and the user settings.

`USER_PERMISSIONS_CHAT_PARAMS`

Type: bool
Default: True
Description: When USER_PERMISSIONS_CHAT_CONTROLS is enabled, this setting specifically controls the visibility of the "Advanced Parameters" section within the chat controls panel.

`USER_PERMISSIONS_CHAT_FILE_UPLOAD`

Type: bool
Default: True
Description: Enables or disables user permission to upload files to chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_WEB_UPLOAD`

Type: bool
Default: True
Description: Enables or disables user permission to attach web pages (URLs) in chats via the "Attach Webpage" option. When set to False, the "Attach Webpage" button is hidden for non-admin users. Also configurable per-group in Admin Panel → Users → Groups → Permissions → Chat Permissions → Allow Web Upload.

`USER_PERMISSIONS_CHAT_DELETE`

Type: bool
Default: True
Description: Enables or disables user permission to delete chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_EDIT`

Type: bool
Default: True
Description: Enables or disables user permission to edit chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_DELETE_MESSAGE`

Type: bool
Default: True
Description: Enables or disables user permission to delete individual messages within chats. This provides granular control over message deletion capabilities separate from full chat deletion.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_CONTINUE_RESPONSE`

Type: bool
Default: True
Description: Enables or disables user permission to continue AI responses. When disabled, users cannot use the "Continue Response" button, which helps prevent potential system prompt leakage through response continuation manipulation.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_REGENERATE_RESPONSE`

Type: bool
Default: True
Description: Enables or disables user permission to regenerate AI responses. Controls access to both the standard regenerate button and the guided regeneration menu.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_RATE_RESPONSE`

Type: bool
Default: True
Description: Enables or disables user permission to rate AI responses using the thumbs up/down feedback system. This controls access to the response rating functionality for evaluation and feedback collection.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_STT`

Type: bool
Default: True
Description: Enables or disables user permission to use Speech-to-Text in chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_TTS`

Type: bool
Default: True
Description: Enables or disables user permission to use Text-to-Speech in chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_CALL`

Type: str
Default: True
Description: Enables or disables user permission to make calls in chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_MULTIPLE_MODELS`

Type: str
Default: True
Description: Enables or disables user permission to use multiple models in chats.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_TEMPORARY`

Type: bool
Default: True
Description: Enables or disables user permission to create temporary chats. Note: Temporary chats disable backend document parsing for privacy.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_CHAT_TEMPORARY_ENFORCED`

Type: str
Default: False
Description: Enables or disables enforced temporary chats for users.
Persistence: This environment variable is a PersistentConfig variable.

Feature Permissions

`USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS`

Type: str
Default: False
Description: Enables or disables user permission to access direct tool servers.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_WEB_SEARCH`

Type: str
Default: True
Description: Enables or disables user permission to use the web search feature.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_IMAGE_GENERATION`

Type: str
Default: True
Description: Enables or disables user permission to use the image generation feature.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`

Type: str
Default: True
Description: Enables or disables user permission to use code interpreter feature.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_MEMORIES`

Type: str
Default: True
Description: Enables or disables user permission to use the memory feature.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_FOLDERS`

Type: str
Default: True
Description: Enables or disables the visibility of the Folders feature (chat sidebar) to users.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_NOTES`

Type: str
Default: True
Description: Enables or disables the visibility of the Notes feature to users.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_CHANNELS`

Type: str
Default: True
Description: Enables or disables the ability for users to create their own group channels.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_FEATURES_API_KEYS`

Type: bool
Default: False
Description: Sets the permission for API key creation feature for users. When enabled, users will have the ability to create and manage API keys for programmatic access.
Persistence: This environment variable is a PersistentConfig variable.

info

For API Key creation (and the API keys themselves):

This setting controls API key creation permission for non-admin users (directly or via User Groups)
API keys must also be globally enabled using ENABLE_API_KEYS

Note: Administrators can generate API keys whenever ENABLE_API_KEYS is enabled, even without features.api_keys. See the Authentication Setup for API Key guide for detailed setup instructions.

Workspace Permissions

`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS`

Type: bool
Default: False
Description: Enables or disables user permission to access workspace models.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS`

Type: bool
Default: False
Description: Enables or disables user permission to access workspace knowledge.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS`

Type: bool
Default: False
Description: Enables or disables user permission to access workspace prompts.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS`

Type: bool
Default: False
Description: Enables or disables user permission to access workspace tools.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_SKILLS_ACCESS`

Type: bool
Default: False
Description: Enables or disables user permission to access workspace skills.
Persistence: This environment variable is a PersistentConfig variable.

These settings control whether users can share workspace items with other users privately (non-public sharing).

`USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_SHARING`

Type: str
Default: False
Description: Enables or disables private sharing of workspace models.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_SHARING`

Type: str
Default: False
Description: Enables or disables private sharing of workspace knowledge.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_SHARING`

Type: str
Default: False
Description: Enables or disables private sharing of workspace prompts.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_SHARING`

Type: str
Default: False
Description: Enables or disables private sharing of workspace tools.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_SHARING`

Type: str
Default: False
Description: Enables or disables private sharing of workspace skills.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_NOTES_ALLOW_SHARING`

Type: str
Default: True
Description: Enables or disables private sharing of notes.
Persistence: This environment variable is a PersistentConfig variable.

These settings control whether users can share workspace items publicly.

`USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_PUBLIC_SHARING`

Type: str
Default: False
Description: Enables or disables public sharing of workspace models.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_PUBLIC_SHARING`

Type: str
Default: False
Description: Enables or disables public sharing of workspace knowledge.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_PUBLIC_SHARING`

Type: str
Default: False
Description: Enables or disables public sharing of workspace prompts.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_PUBLIC_SHARING`

Type: str
Default: False
Description: Enables or disables public sharing of workspace tools.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_PUBLIC_SHARING`

Type: str
Default: False
Description: Enables or disables public sharing of workspace skills.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING`

Type: str
Default: True
Description: Enables or disables public sharing of notes.
Persistence: This environment variable is a PersistentConfig variable.

Access Grants

`USER_PERMISSIONS_ACCESS_GRANTS_ALLOW_USERS`

Type: bool
Default: True
Description: Controls whether non-admin users can share resources (knowledge bases, models, prompts, notes, skills, and tools) with specific individual users. When set to False, individual user grants are silently stripped from access grant lists — group sharing and public sharing remain unaffected. Admins always retain the ability to share with individual users regardless of this setting. Also configurable per-group in Admin Panel → Users → Groups → Permissions → Access Grants → Allow Sharing With Users.

Import / Export

`USER_PERMISSIONS_WORKSPACE_MODELS_IMPORT`

Type: str
Default: True
Description: Enables or disables user permission to import workspace models.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_MODELS_EXPORT`

Type: str
Default: True
Description: Enables or disables user permission to export workspace models.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_PROMPTS_IMPORT`

Type: str
Default: True
Description: Enables or disables user permission to import workspace prompts.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_PROMPTS_EXPORT`

Type: str
Default: True
Description: Enables or disables user permission to export workspace prompts.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_TOOLS_IMPORT`

Type: str
Default: False
Description: Enables or disables user permission to import workspace tools.
Persistence: This environment variable is a PersistentConfig variable.

`USER_PERMISSIONS_WORKSPACE_TOOLS_EXPORT`

Type: str
Default: False
Description: Enables or disables user permission to export workspace tools.
Persistence: This environment variable is a PersistentConfig variable.

Settings Permissions

`USER_PERMISSIONS_SETTINGS_INTERFACE`

Type: bool
Default: True
Description: Enables or disables user / group permissions for the interface settings section in the Settings Modal.
Persistence: This environment variable is a PersistentConfig variable.

Misc Environment Variables

These variables are not specific to Open WebUI but can still be valuable in certain contexts.

Cloud Storage

`STORAGE_PROVIDER`

Type: str
Options:
- s3 - uses the S3 client library and related environment variables mentioned in Amazon S3 Storage
- gcs - uses the GCS client library and related environment variables mentioned in Google Cloud Storage
- azure - uses the Azure client library and related environment variables mentioned in Microsoft Azure Storage
Default: empty string (' '), which defaults to local
Description: Sets the storage provider.

Amazon S3 Storage

`S3_ACCESS_KEY_ID`

Type: str
Description: Sets the access key ID for S3 storage.

`S3_ADDRESSING_STYLE`

Type: str
Default: None
Description: Specifies the addressing style to use for S3 storage (e.g., 'path', 'virtual').

`S3_BUCKET_NAME`

Type: str
Description: Sets the bucket name for S3 storage.

`S3_ENDPOINT_URL`

Type: str
Description: Sets the endpoint URL for S3 storage.

info

If the endpoint is an S3-compatible provider like MinIO that uses a TLS certificate signed by a private CA, set the environment variable AWS_CA_BUNDLE to the path of your PEM-encoded CA certificates file. See the Amazon SDK Docs for more information.

`S3_KEY_PREFIX`

Type: str
Description: Sets the key prefix for a S3 object.

`S3_REGION_NAME`

Type: str
Description: Sets the region name for S3 storage.

`S3_SECRET_ACCESS_KEY`

Type: str
Description: Sets the secret access key for S3 storage.

`S3_USE_ACCELERATE_ENDPOINT`

Type: str
Default: False
Description: Specifies whether to use the accelerated endpoint for S3 storage.

`S3_ENABLE_TAGGING`

Type: str
Default: False
Description: Enables S3 object tagging after uploads for better organization, searching, and integration with file management policies. Always set to False when using Cloudflare R2, as R2 does not support object tagging.

Google Cloud Storage

`GOOGLE_APPLICATION_CREDENTIALS_JSON`

Type: str
Description: Contents of Google Application Credentials JSON file.
- Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Google Metadata server if run on a Google Compute Engine.
- A file can be generated for a service account following this guide.

`GCS_BUCKET_NAME`

Type: str
Description: Sets the bucket name for Google Cloud Storage. Bucket must already exist.

Microsoft Azure Storage

`AZURE_STORAGE_ENDPOINT`

Type: str
Description: Sets the endpoint URL for Azure Storage.

`AZURE_STORAGE_CONTAINER_NAME`

Type: str
Description: Sets the container name for Azure Storage.

`AZURE_STORAGE_KEY`

Type: str
Description: Set the access key for Azure Storage.
- Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Managed Identity if run in Azure services.

OpenTelemetry Configuration

Additional Dependencies May Be Required

OpenTelemetry support requires additional Python dependencies that may not be included by default depending on your installation method (e.g., standard pip install open-webui versus Docker images).

If you encounter ImportError or missing module errors related to OpenTelemetry, you may need to install them manually:

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

`ENABLE_OTEL`

Type: bool
Default: False
Description: Enables or disables OpenTelemetry for observability. When enabled, tracing, metrics, and logging data can be collected and exported to an OTLP endpoint.

`ENABLE_OTEL_TRACES`

Type: bool
Default: False
Description: Enables or disables OpenTelemetry traces collection and export. This variable works in conjunction with ENABLE_OTEL.

`ENABLE_OTEL_METRICS`

Type: bool
Default: False
Description: Enables or disables OpenTelemetry metrics collection and export. This variable works in conjunction with ENABLE_OTEL.

`ENABLE_OTEL_LOGS`

Type: bool
Default: False
Description: Enables or disables OpenTelemetry logging export. When enabled, application logs are sent to the configured OTLP endpoint. This variable works in conjunction with ENABLE_OTEL.

`OTEL_EXPORTER_OTLP_ENDPOINT`

Type: str
Default: http://localhost:4317
Description: Specifies the default OTLP (OpenTelemetry Protocol) endpoint for exporting traces, metrics, and logs. This can be overridden for metrics if OTEL_METRICS_EXPORTER_OTLP_ENDPOINT is set, and for logs if OTEL_LOGS_EXPORTER_OTLP_ENDPOINT is set.

`OTEL_METRICS_EXPORTER_OTLP_ENDPOINT`

Type: str
Default: Value of OTEL_EXPORTER_OTLP_ENDPOINT
Description: Specifies the dedicated OTLP endpoint for exporting OpenTelemetry metrics. If not set, it defaults to the value of OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for traces and metrics are used.

`OTEL_LOGS_EXPORTER_OTLP_ENDPOINT`

Type: str
Default: Value of OTEL_EXPORTER_OTLP_ENDPOINT
Description: Specifies the dedicated OTLP endpoint for exporting OpenTelemetry logs. If not set, it defaults to the value of OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for logs, traces, and metrics are used.

`OTEL_EXPORTER_OTLP_INSECURE`

Type: bool
Default: False
Description: If set to True, the OTLP exporter will use an insecure connection (e.g., HTTP for gRPC) for traces. For metrics, its behavior is governed by OTEL_METRICS_EXPORTER_OTLP_INSECURE, and for logs by OTEL_LOGS_EXPORTER_OTLP_INSECURE.

`OTEL_METRICS_EXPORTER_OTLP_INSECURE`

Type: bool
Default: Value of OTEL_EXPORTER_OTLP_INSECURE
Description: If set to True, the OTLP exporter will use an insecure connection for metrics. If not specified, it uses the value of OTEL_EXPORTER_OTLP_INSECURE.

`OTEL_LOGS_EXPORTER_OTLP_INSECURE`

Type: bool
Default: Value of OTEL_EXPORTER_OTLP_INSECURE
Description: If set to True, the OTLP exporter will use an insecure connection for logs. If not specified, it uses the value of OTEL_EXPORTER_OTLP_INSECURE.

`OTEL_SERVICE_NAME`

Type: str
Default: open-webui
Description: Sets the service name that will be reported to your OpenTelemetry collector or observability platform. This helps identify your Open WebUI instance.

`OTEL_RESOURCE_ATTRIBUTES`

Type: str
Default: Empty string (' ')
Description: Allows you to define additional resource attributes to be attached to all telemetry data, in a comma-separated key1=val1,key2=val2 format.

`OTEL_TRACES_SAMPLER`

Type: str
Options: parentbased_always_on, always_on, always_off, parentbased_always_off, etc.
Default: parentbased_always_on
Description: Configures the sampling strategy for OpenTelemetry traces. This determines which traces are collected and exported to reduce data volume.

`OTEL_BASIC_AUTH_USERNAME`

Type: str
Default: Empty string (' ')
Description: Sets the username for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.

`OTEL_BASIC_AUTH_PASSWORD`

Type: str
Default: Empty string (' ')
Description: Sets the password for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.

`OTEL_METRICS_EXPORT_INTERVAL_MILLIS`

Type: int
Default: 10000 (10 seconds)
Description: Controls how often OpenTelemetry metrics are exported, in milliseconds. The default of 10 seconds produces approximately 6 data points per minute. Lower this value for higher resolution, or increase it to reduce cost on platforms that charge per data point (e.g. Grafana Cloud recommends staying below 1 DPM — set to 60000 for one export per minute).

`OTEL_METRICS_BASIC_AUTH_USERNAME`

Type: str
Default: Value of OTEL_BASIC_AUTH_USERNAME
Description: Sets the username for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_USERNAME.

`OTEL_METRICS_BASIC_AUTH_PASSWORD`

Type: str
Default: Value of OTEL_BASIC_AUTH_PASSWORD
Description: Sets the password for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_PASSWORD.

`OTEL_LOGS_BASIC_AUTH_USERNAME`

Type: str
Default: Value of OTEL_BASIC_AUTH_USERNAME
Description: Sets the username for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_USERNAME.

`OTEL_LOGS_BASIC_AUTH_PASSWORD`

Type: str
Default: Value of OTEL_BASIC_AUTH_PASSWORD
Description: Sets the password for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of OTEL_BASIC_AUTH_PASSWORD.

`OTEL_OTLP_SPAN_EXPORTER`

Type: str
Options: grpc, http
Default: grpc
Description: Specifies the default protocol for exporting OpenTelemetry traces (gRPC or HTTP). This can be overridden for metrics if OTEL_METRICS_OTLP_SPAN_EXPORTER is set, and for logs if OTEL_LOGS_OTLP_SPAN_EXPORTER is set.

`OTEL_METRICS_OTLP_SPAN_EXPORTER`

Type: str
Options: grpc, http
Default: Value of OTEL_OTLP_SPAN_EXPORTER
Description: Specifies the protocol for exporting OpenTelemetry metrics (gRPC or HTTP). If not specified, it uses the value of OTEL_OTLP_SPAN_EXPORTER.

`OTEL_LOGS_OTLP_SPAN_EXPORTER`

Type: str
Options: grpc, http
Default: Value of OTEL_OTLP_SPAN_EXPORTER
Description: Specifies the protocol for exporting OpenTelemetry logs (gRPC or HTTP). If not specified, it uses the value of OTEL_OTLP_SPAN_EXPORTER.

Database Pool

`DATABASE_URL`

Type: str
Default: sqlite:///${DATA_DIR}/webui.db
Description: Specifies the complete database connection URL, following SQLAlchemy's URL scheme. This variable takes precedence over individual database connection parameters if explicitly set.

info

For PostgreSQL support, ensure you installed with pip install open-webui[all] instead of the basic installation. Supports SQLite, Postgres, and encrypted SQLite via SQLCipher. Changing the URL does not migrate data between databases.

Documentation on the URL scheme is available here.

If your database password contains special characters, please ensure they are properly URL-encoded. For example, a password like p@ssword should be encoded as p%40ssword.

For configuration using individual parameters or encrypted SQLite, see the relevant sections below.

`ENABLE_DB_MIGRATIONS`

Type: bool
Default: True
Description: Controls whether database migrations are automatically run on startup. In multi-pod or multi-worker deployments, set this to False on all pods except one to designate a "master" pod responsible for migrations, preventing race conditions or schema corruption.

warning

Required for Multi-Replica Setups For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you MUST use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency.

`DATABASE_TYPE`

Type: str
Default: None (automatically set to sqlite if DATABASE_URL uses default SQLite path)
Description: Specifies the database type (e.g., sqlite, postgresql, sqlite+sqlcipher). This is used in conjunction with other individual parameters to construct the DATABASE_URL if a complete DATABASE_URL is not explicitly defined.
Persistence: No

`DATABASE_USER`

Type: str
Default: None
Description: Specifies the username for database authentication. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
Persistence: No

`DATABASE_PASSWORD`

Type: str
Default: None
Description: Specifies the password for database authentication. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined. If your password contains special characters, please ensure they are properly URL-encoded.
Persistence: No

`DATABASE_HOST`

Type: str
Default: None
Description: Specifies the hostname or IP address of the database server. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
Persistence: No

`DATABASE_PORT`

Type: int
Default: None
Description: Specifies the port number of the database server. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
Persistence: No

`DATABASE_NAME`

Type: str
Default: None
Description: Specifies the name of the database to connect to. This is used to construct the DATABASE_URL when a complete DATABASE_URL is not explicitly defined.
Persistence: No

info

When DATABASE_URL is not explicitly set, Open WebUI will attempt to construct it using a combination of DATABASE_TYPE, DATABASE_USER, DATABASE_PASSWORD, DATABASE_HOST, DATABASE_PORT, and DATABASE_NAME. For this automatic construction to occur, all of these individual parameters must be provided. If any are missing, the default DATABASE_URL (SQLite file) or any explicitly set DATABASE_URL will be used instead.

`DATABASE_USER_ACTIVE_STATUS_UPDATE_INTERVAL`

Type: float
Default: None
Description: Sets the minimum time interval in seconds between user active status updates in the database. Helps reduce write operations for high-traffic instances. Set to 0.0 to update on every activity.

`DATABASE_ENABLE_SESSION_SHARING`

Type: bool
Default: False
Description: Controls database session sharing behavior. When enabled (True), get_db_context reuses existing database sessions, which can improve performance and scalability in high-concurrency environments. When disabled (False), new sessions are always created.

Recommendations by Database Type

SQLite: Keep this setting disabled (default False). Enabling session sharing on SQLite with limited hardware resources may cause performance issues.
PostgreSQL: Consider enabling this setting (True) for improved performance, especially in multi-user or high-concurrency deployments.

This setting is very deployment-specific. Users are encouraged to experiment based on their hardware specs and database choice to find the optimal configuration.

warning

Enabling this on low-spec hardware (e.g., Raspberry Pi, containers with limited CPU allocation) may cause significant slowdowns or timeouts. If you experience slow admin page loads or API timeouts after upgrading, ensure this setting is disabled.

Encrypted SQLite with SQLCipher

For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.

Additional Dependencies Required

SQLCipher encryption requires additional dependencies that are not included by default. Before using this feature, you must install:

The SQLCipher system library (e.g., libsqlcipher-dev on Debian/Ubuntu, sqlcipher on macOS via Homebrew)
The sqlcipher3-wheels Python package (pip install sqlcipher3-wheels)

For Docker users, this means building a custom image with these dependencies included.

To enable encryption, you must configure two environment variables:

Set DATABASE_TYPE="sqlite+sqlcipher".
Set DATABASE_PASSWORD="your-secure-password".

When these are set and a full DATABASE_URL is not explicitly defined, Open WebUI will automatically create and use an encrypted database file at ./data/webui.db.

danger

The DATABASE_PASSWORD environment variable is required when using sqlite+sqlcipher.
The DATABASE_TYPE variable tells Open WebUI which connection logic to use. Setting it to sqlite+sqlcipher activates the encryption feature.

Ensure the database password is kept secure, as it is needed to decrypt and access all application data.

Migrating Existing Data to SQLCipher

Open WebUI does not support automatic migration from an unencrypted SQLite database to an encrypted SQLCipher database. If you enable SQLCipher on an existing installation, the application will fail to read your existing unencrypted data.

To use SQLCipher with existing data, you must either start fresh (with users exporting/re-importing chats), manually migrate the database using external SQLite/SQLCipher tools, use filesystem-level encryption (LUKS/BitLocker) instead, or switch to PostgreSQL.

`DATABASE_SCHEMA`

Type: str
Default: None
Description: Specifies the database schema to connect to.

`DATABASE_POOL_SIZE`

Type: int
Default: None
Description: Specifies the pooling strategy and size of the database pool. By default SQLAlchemy will automatically chose the proper pooling strategy for the selected database connection. A value of 0 disables pooling. A value larger 0 will set the pooling strategy to QueuePool and the pool size accordingly.

High-Concurrency Deployments

For deployments with many concurrent users, consider increasing both DATABASE_POOL_SIZE and DATABASE_POOL_MAX_OVERFLOW. A good starting point is DATABASE_POOL_SIZE=15 and DATABASE_POOL_MAX_OVERFLOW=20.

Important: The combined total (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) should remain well below your database server's max_connections limit. PostgreSQL defaults to 100 max connections, so keeping the combined total under 50-80 per Open WebUI instance is recommended to leave room for other clients and maintenance connections.

Pool Size Multiplies with Concurrency

Each Open WebUI process maintains its own independent connection pool. This applies whether you're running multiple Uvicorn workers (UVICORN_WORKERS > 1), multiple Kubernetes pods, Docker Swarm replicas, or any other multi-instance deployment.

The actual maximum number of database connections is:

Total connections = (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) × Number of processes/instances

For example, with DATABASE_POOL_SIZE=15, DATABASE_POOL_MAX_OVERFLOW=20, and 4 instances (whether workers, pods, or replicas), you could open up to 140 connections (35 × 4).

When calculating pool settings, always account for this multiplier to avoid exhausting your database's max_connections limit. This is a fundamental limitation—connection pools cannot be shared across separate processes or containers.

`DATABASE_POOL_MAX_OVERFLOW`

Type: int
Default: 0
Description: Specifies the database pool max overflow. This allows additional connections beyond DATABASE_POOL_SIZE during traffic spikes.

info

More information about this setting can be found here.

`DATABASE_POOL_TIMEOUT`

Type: int
Default: 30
Description: Specifies the database pool timeout in seconds to get a connection.

info

More information about this setting can be found here.

`DATABASE_POOL_RECYCLE`

Type: int
Default: 3600
Description: Specifies the database pool recycle time in seconds.

info

More information about this setting can be found here.

`DATABASE_ENABLE_SQLITE_WAL`

Type: bool
Default: False
Description: Enables or disables SQLite WAL (Write-Ahead Logging) mode. When enabled, SQLite transactions can be managed more efficiently, allowing multiple readers and one writer concurrently, which can improve database performance, especially under high concurrency. This setting only applies to SQLite databases.

Redis

`REDIS_URL`

Type: str
Description: Specifies the URL of the Redis instance or cluster host for storing application state.
Examples:
- redis://localhost:6379/0
- rediss://:password@localhost:6379/0 (with password and TLS)
- rediss://redis-cluster.redis.svc.cluster.local:6379/0?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt&ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt (with mTLS)

warning

Required for Multi-Worker and Multi-Node Deployments

When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set the REDIS_URL value. Without it, the following issues will occur:

Session management will fail across workers
Application state will be inconsistent between instances
Websocket connections will not function properly in distributed setups
Users may experience intermittent authentication failures

Redis serves as the central state store that allows multiple Open WebUI instances to coordinate and share critical application data.

info

Single Instance Deployments

If you're running Open WebUI as a single instance with UVICORN_WORKERS=1 (the default), Redis is not required. The application will function normally without it.

danger

Critical Redis Server Configuration — Prevent Connection Exhaustion

Open WebUI uses Redis for token validation, WebSocket management, and session storage. Each user action can create Redis connections. If your Redis server is misconfigured, connections will accumulate over time until the limit is reached, causing 500 Internal Server Errors and preventing all users from logging in.

You must configure these settings in your redis.conf (not Open WebUI environment variables):

Setting	Bad Default	Recommended	Why
`maxclients`	1000 (some distros)	`10000` or higher	Low limits cause "max number of clients reached" errors
`timeout`	0 (never close)	`1800` (30 minutes)	Without timeout, idle connections accumulate forever

Example redis.conf settings:

maxclients 10000
timeout 1800

Symptoms of this misconfiguration:

Works fine for days/weeks, then suddenly all logins fail with 500 errors
redis.exceptions.ConnectionError: max number of clients reached in logs
Problem appears to "fix itself" temporarily, then returns

Why this happens: With timeout 0, every Redis connection stays open indefinitely. Over days or weeks, connections from token checks, WebSocket events, and session validations accumulate. Once maxclients is reached, no new connections can be made, and authentication fails completely.

To check your current connection count:

redis-cli INFO clients | grep connected_clients

To verify your settings:

redis-cli CONFIG GET maxclients
redis-cli CONFIG GET timeout

`REDIS_SENTINEL_HOSTS`

Type: str
Description: Comma-separated list of Redis Sentinels for app state. If specified, the "hostname" in REDIS_URL will be interpreted as the Sentinel service name.

`REDIS_SENTINEL_PORT`

Type: int
Default: 26379
Description: Sentinel port for app state Redis.

`REDIS_CLUSTER`

Type: bool
Default: False
Description: Connect to a Redis Cluster instead of a single instance or using Redis Sentinels. If True, REDIS_URL must also be defined. This mode is compatible with AWS Elasticache Serverless and other Redis Cluster implementations.

info

This option has no effect if REDIS_SENTINEL_HOSTS is defined.

OpenTelemetry Support

Redis Cluster mode is fully compatible with OpenTelemetry instrumentation. When ENABLE_OTEL is enabled, Redis operations are properly traced regardless of whether you're using a single Redis instance or Redis Cluster mode.

`REDIS_KEY_PREFIX`

Type: str
Default: open-webui
Description: Customizes the Redis key prefix used for storing configuration values. This allows multiple Open WebUI instances to share the same Redis instance without key conflicts. When operating in Redis cluster mode, the prefix is formatted as {prefix}: (e.g., {open-webui}:config:*) to enable multi-key operations on configuration keys within the same hash slot.

`REDIS_SOCKET_CONNECT_TIMEOUT`

Type: float (seconds) or empty string for None
Default: None (no timeout, uses redis-py library default)
Description: Sets the socket connection timeout in seconds for Redis and Sentinel connections. This timeout applies to the initial TCP connection establishment. When set, it prevents indefinite blocking when attempting to connect to unreachable Redis nodes.

danger

Critical for Redis Sentinel Deployments

Without a socket connection timeout, Redis Sentinel failover can cause the application to hang indefinitely when a master node goes offline. The application may become completely unresponsive and even fail to restart.

For Sentinel deployments, it is strongly recommended to set this value (e.g., REDIS_SOCKET_CONNECT_TIMEOUT=5).

warning

Interaction with WEBSOCKET_REDIS_OPTIONS

If you explicitly set WEBSOCKET_REDIS_OPTIONS, this variable will not apply to the AsyncRedisManager used for websocket communication. In that case, you must include socket_connect_timeout directly within WEBSOCKET_REDIS_OPTIONS:

WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}'

If WEBSOCKET_REDIS_OPTIONS is not set, REDIS_SOCKET_CONNECT_TIMEOUT will be applied to websocket connections automatically.

`REDIS_SENTINEL_MAX_RETRY_COUNT`

Type: int
Default: 2
Description: Sets the maximum number of retries for Redis operations when using Sentinel fail-over. This is a critical high-availability setting that allows the application time for master election and promotion. If your Sentinel down-after-milliseconds is high, you should tune this value accordingly to ensure the service survives the failover window without dropping connections.

`REDIS_RECONNECT_DELAY`

Type: float (milliseconds)
Default: None
Description: Optional reconnect delay in milliseconds for Redis Sentinel retry logic, applied consistently across both synchronous and asynchronous Redis operations. This improves stability during Sentinel failover by preventing tight retry loops. When unset or invalid, retry behavior remains unchanged.

`WEBSOCKET_REDIS_LOCK_TIMEOUT`

Type: int
Default: 60
Description: Sets the timeout in seconds for Redis locks used by the websocket manager.

`ENABLE_WEBSOCKET_SUPPORT`

Type: bool
Default: True
Description: Enables websocket support in Open WebUI.

warning

Required for Multi-Worker and Multi-Node Deployments

Session management will fail across workers
Application state will be inconsistent between instances
Websocket connections will not function properly in distributed setups
Users may experience intermittent authentication failures

`WEBSOCKET_MANAGER`

Type: str
Default: "" (empty string)
Description: Specifies the websocket manager to use. Allowed values include: redis

warning

Required for Multi-Worker and Multi-Node Deployments

Session management will fail across workers
Application state will be inconsistent between instances
Websocket connections will not function properly in distributed setups
Users may experience intermittent authentication failures

`WEBSOCKET_REDIS_URL`

Type: str
Default: ${REDIS_URL}
Description: Specifies the URL of the Redis instance or cluster host for websocket communication. It is distinct from REDIS_URL and in practice, it is recommended to set both.

warning

Required for Multi-Worker and Multi-Node Deployments

Session management will fail across workers
Application state will be inconsistent between instances
Websocket connections will not function properly in distributed setups
Users may experience intermittent authentication failures

`WEBSOCKET_SENTINEL_HOSTS`

Type: str
Description: Comma-separated list of Redis Sentinels for websocket. If specified, the "hostname" in WEBSOCKET_REDIS_URL will be interpreted as the Sentinel service name.

`WEBSOCKET_SENTINEL_PORT`

Type: int
Default: 26379
Description: Sentinel port for websocket Redis.

`WEBSOCKET_REDIS_CLUSTER`

Type: bool
Default: ${REDIS_CLUSTER}
Description: Specifies that websocket should communicate with a Redis Cluster instead of a single instance or using Redis Sentinels. If True, WEBSOCKET_REDIS_URL and/or REDIS_URL must also be defined.

info

This option has no effect if WEBSOCKET_SENTINEL_HOSTS is defined.

`WEBSOCKET_REDIS_OPTIONS`

Type: str
Default: {} (empty, which allows REDIS_SOCKET_CONNECT_TIMEOUT to apply if set)
Description: A string representation of a dictionary containing additional Redis connection options for the websocket Redis client (AsyncRedisManager). This allows you to specify advanced connection parameters such as SSL settings, timeouts, or other Redis client configurations that are not covered by the standard WEBSOCKET_REDIS_URL. The string should be formatted as valid JSON. For example: {"retry_on_timeout": true, "socket_connect_timeout": 5, "socket_timeout": 5, "max_connections": 8}. All JSON encodable options listed here can be used.

warning

AWS SSM and Docker compose cannot ingest raw JSON, as such you need to escape any double quotes like the following: {\"retry_on_timeout\": true, \"socket_connect_timeout\": 5, \"socket_timeout\": 5, \"max_connections\": 8}

info

Precedence with REDIS_SOCKET_CONNECT_TIMEOUT

When this variable is left empty (default), REDIS_SOCKET_CONNECT_TIMEOUT is automatically applied to websocket connections if set. However, if you explicitly set WEBSOCKET_REDIS_OPTIONS to any value, REDIS_SOCKET_CONNECT_TIMEOUT will not be injected—you must include socket_connect_timeout manually within this JSON if needed.

`WEBSOCKET_SERVER_LOGGING`

Type: bool
Default: false
Description: Controls logging for SocketIO server related to websocket operations.

warning

This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.

`WEBSOCKET_SERVER_ENGINEIO_LOGGING`

Type: bool
Default: Falls back to WEBSOCKET_SERVER_LOGGING if not set, otherwise false
Description: Controls logging for Engine.IO server related to websocket operations. If not explicitly set, this inherits the value from WEBSOCKET_SERVER_LOGGING.

warning

This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.

`WEBSOCKET_SERVER_PING_TIMEOUT`

Type: int
Default: 20
Description: The timeout for a ping to Redis in seconds.

`WEBSOCKET_SERVER_PING_INTERVAL`

Type: int
Default: 25
Description: The frequency for a ping to Redis in seconds.

`WEBSOCKET_EVENT_CALLER_TIMEOUT`

Type: int
Default: 300
Description: Sets the timeout in seconds for the sio.call() used in event_call events. This controls how long the server waits for a user to respond to interactive prompts, forms, or dropdowns generated by tools and actions using event_call (e.g., execute() type events). Increase this value if users need more time to fill out forms or make decisions presented by event calls.

`ENABLE_STAR_SESSIONS_MIDDLEWARE`

Type: bool
Default: False
Description: Enables Redis-based session storage for OAuth authentication flows using the StarSessions middleware. When enabled, OAuth session state is stored in Redis instead of browser cookies, which can help resolve CSRF errors in multi-replica deployments where session data needs to be shared across pods. Experimental feature that enables Redis-based session storage for OAuth flows using StarSessions middleware, helping resolve CSRF errors in multi-replica deployments.
Persistence: This is an experimental environment variable.

warning

Experimental Feature - Known Limitations

This feature is currently experimental and has known compatibility issues:

Redis Sentinel and Redis Cluster configurations are not yet supported and will cause authentication failures if this setting is enabled
Only basic Redis setups (single instance or standard Redis URL) are currently compatible
This feature was introduced to address CSRF "mismatching_state" errors in multi-pod deployments, but it is disabled by default due to ongoing compatibility work

Only enable this setting if:

You are experiencing persistent CSRF errors during OAuth login in a multi-replica deployment
You are using a basic Redis setup (not Sentinel or Cluster)
You have confirmed that WEBUI_SECRET_KEY is set to the same value across all replicas
You understand this is an experimental feature that may change or be removed in future releases

For most deployments, the default browser cookie-based session management is sufficient and more stable.

Uvicorn Settings

`UVICORN_WORKERS`

Type: int
Default: 1
Description: Controls the number of worker processes that Uvicorn spawns to handle requests. Each worker runs its own instance of the application in a separate process.

info

When deploying in orchestrated environments like Kubernetes or using Helm charts, it's recommended to keep UVICORN_WORKERS set to 1. Container orchestration platforms already provide their own scaling mechanisms through pod replication, and using multiple workers inside containers can lead to resource allocation issues and complicate horizontal scaling strategies.

If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-worker setups are set accordingly.

ChromaDB Not Compatible with Multiple Workers

The default vector database (ChromaDB) uses a local SQLite-backed PersistentClient. SQLite connections are not fork-safe — when uvicorn forks multiple workers, each process inherits the same SQLite connection, and concurrent writes will crash workers instantly (Child process died).

If you set UVICORN_WORKERS > 1, you must either switch to a client-server vector database (PGVector, Milvus, Qdrant) via VECTOR_DB, or run ChromaDB as a separate server and set CHROMA_HTTP_HOST.

Database Migrations with Multiple Workers / Multi-Pod Deployments

When UVICORN_WORKERS > 1 or when running multiple replicas, starting the application can trigger concurrent database migrations from multiple processes, potentially causing database schema corruption or inconsistent states.

Recommendation: To handle migrations safely in multi-process/multi-pod environments, you can:

Designate a Master (Recommended): Set ENABLE_DB_MIGRATIONS=False on all but one instance/worker. The instance with ENABLE_DB_MIGRATIONS=True (default) will handle the migration, while others will wait or skip it.
Scale Down: Temporarily scale down to a single instance/worker to let migrations finish before scaling back up.

For Kubernetes, Helm, and Orchestrated Setups: It is recommended to use the ENABLE_DB_MIGRATIONS variable to designate a specific pod for migrations, or use an init container/job to handle migrations before scaling up the main application pods. This ensures schema updates are applied exactly once.

Cache Settings

`CACHE_CONTROL`

Type: str
Default: Not set (no Cache-Control header added)
Description: Sets the Cache-Control header for all HTTP responses. Supports standard directives like public, private, no-cache, no-store, must-revalidate, max-age=seconds, etc. If an invalid value is provided, defaults to "no-store, max-age=0" (no caching).
Examples:
- "private, max-age=86400" - Cache privately for 24 hours
- "public, max-age=3600, must-revalidate" - Cache publicly for 1 hour, then revalidate
- "no-cache, no-store, must-revalidate" - Never cache

Proxy Settings

Open WebUI supports using proxies for HTTP and HTTPS retrievals. To specify proxy settings, Open WebUI uses the following environment variables:

`http_proxy`

Type: str
Description: Sets the URL for the HTTP proxy.

`https_proxy`

Type: str
Description: Sets the URL for the HTTPS proxy.

`no_proxy`

Type: str
Description: Lists domain extensions (or IP addresses) for which the proxy should not be used, separated by commas. For example, setting no_proxy to '.mit.edu' ensures that the proxy is bypassed when accessing documents from MIT.

Install Required Python Packages

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_PIP_INSTALL_FRONTMATTER_REQUIREMENTS`

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.

Security Hardening for Production

Strongly recommended: set ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=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:

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
Description: Specifies additional command-line options that pip should use when installing packages. For example, you can include flags such as --upgrade, --user, or --no-cache-dir to control the installation process.

`PIP_PACKAGE_INDEX_OPTIONS`

Type: str
Description: Defines custom package index behavior for pip. This can include specifying additional or alternate index URLs (e.g., --extra-index-url), authentication credentials, or other parameters to manage how packages are retrieved from different locations.

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

Overview​

Important Note on PersistentConfig Environment Variables​

Troubleshooting Ignored Environment Variables 🛠️​

Option 1: Using ENABLE_PERSISTENT_CONFIG (Temporary Fix)​

Option 2: Update via Admin UI (Recommended)​

Option 3: Manual Database Update (Last Resort / Lock-out Recovery)​

Option 4: Resetting for a Fresh Install​

App/Backend​

General​

WEBUI_URL​

ENABLE_SIGNUP​

ENABLE_SIGNUP_PASSWORD_CONFIRMATION​

WEBUI_ADMIN_EMAIL​

WEBUI_ADMIN_PASSWORD​

WEBUI_ADMIN_NAME​

ENABLE_LOGIN_FORM​

ENABLE_PASSWORD_AUTH​

DEFAULT_LOCALE​

DEFAULT_MODELS​

DEFAULT_PINNED_MODELS​

DEFAULT_MODEL_METADATA​

DEFAULT_MODEL_PARAMS​

DEFAULT_USER_ROLE​

DEFAULT_GROUP_ID​

DEFAULT_GROUP_SHARE_PERMISSION​

PENDING_USER_OVERLAY_TITLE​

PENDING_USER_OVERLAY_CONTENT​

ENABLE_CHANNELS​

ENABLE_FOLDERS​

FOLDER_MAX_FILE_COUNT​

ENABLE_NOTES​

ENABLE_MEMORIES​

WEBHOOK_URL​

ENABLE_ADMIN_EXPORT​

ENABLE_ADMIN_CHAT_ACCESS​

ENABLE_ADMIN_ANALYTICS​

BYPASS_ADMIN_ACCESS_CONTROL​

ENABLE_USER_WEBHOOKS​

RESPONSE_WATERMARK​

THREAD_POOL_SIZE​

ENABLE_CUSTOM_MODEL_FALLBACK​

SHOW_ADMIN_DETAILS​

ENABLE_PUBLIC_ACTIVE_USERS_COUNT​

ENABLE_USER_STATUS​

ENABLE_EASTER_EGGS​

ADMIN_EMAIL​

ENV​

ENABLE_PERSISTENT_CONFIG​

CUSTOM_NAME​

WEBUI_NAME​

PORT​

ENABLE_REALTIME_CHAT_SAVE​

ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION​

CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE​

CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE​

ENABLE_RESPONSES_API_STATEFUL​

BYPASS_MODEL_ACCESS_CONTROL​

WEBUI_BUILD_HASH​

WEBUI_BANNERS​

USE_CUDA_DOCKER​

DOCKER​

USE_CUDA​

DEVICE_TYPE​

EXTERNAL_PWA_MANIFEST_URL​

ENABLE_TITLE_GENERATION​

LICENSE_KEY​

SSL_ASSERT_FINGERPRINT​

ENABLE_COMPRESSION_MIDDLEWARE​

DEFAULT_PROMPT_SUGGESTIONS​

AIOHTTP Client​

AIOHTTP_CLIENT_TIMEOUT​

AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST​

AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST​

AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER​

AIOHTTP_CLIENT_SESSION_SSL​

AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA​

AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL​

REQUESTS_VERIFY​

Directories​

DATA_DIR​

Overview

Important Note on `PersistentConfig` Environment Variables

Troubleshooting Ignored Environment Variables 🛠️

Option 1: Using `ENABLE_PERSISTENT_CONFIG` (Temporary Fix)

Option 2: Update via Admin UI (Recommended)

Option 3: Manual Database Update (Last Resort / Lock-out Recovery)

Option 4: Resetting for a Fresh Install

App/Backend

General

`WEBUI_URL`

`ENABLE_SIGNUP`

`ENABLE_SIGNUP_PASSWORD_CONFIRMATION`

`WEBUI_ADMIN_EMAIL`

`WEBUI_ADMIN_PASSWORD`

`WEBUI_ADMIN_NAME`

`ENABLE_LOGIN_FORM`

`ENABLE_PASSWORD_AUTH`

`DEFAULT_LOCALE`

`DEFAULT_MODELS`

`DEFAULT_PINNED_MODELS`

`DEFAULT_MODEL_METADATA`

`DEFAULT_MODEL_PARAMS`

`DEFAULT_USER_ROLE`

`DEFAULT_GROUP_ID`

`DEFAULT_GROUP_SHARE_PERMISSION`

`PENDING_USER_OVERLAY_TITLE`

`PENDING_USER_OVERLAY_CONTENT`

`ENABLE_CHANNELS`

`ENABLE_FOLDERS`

`FOLDER_MAX_FILE_COUNT`

`ENABLE_NOTES`

`ENABLE_MEMORIES`

`WEBHOOK_URL`

`ENABLE_ADMIN_EXPORT`

`ENABLE_ADMIN_CHAT_ACCESS`

`ENABLE_ADMIN_ANALYTICS`

`BYPASS_ADMIN_ACCESS_CONTROL`

`ENABLE_USER_WEBHOOKS`

`RESPONSE_WATERMARK`

`THREAD_POOL_SIZE`

`ENABLE_CUSTOM_MODEL_FALLBACK`

`SHOW_ADMIN_DETAILS`

`ENABLE_PUBLIC_ACTIVE_USERS_COUNT`

`ENABLE_USER_STATUS`

`ENABLE_EASTER_EGGS`

`ADMIN_EMAIL`

`ENV`

`ENABLE_PERSISTENT_CONFIG`

`CUSTOM_NAME`

`WEBUI_NAME`

`PORT`

`ENABLE_REALTIME_CHAT_SAVE`

`ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION`

`CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE`

`CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE`

`ENABLE_RESPONSES_API_STATEFUL`

`BYPASS_MODEL_ACCESS_CONTROL`

`WEBUI_BUILD_HASH`

`WEBUI_BANNERS`

`USE_CUDA_DOCKER`

`DOCKER`

`USE_CUDA`

`DEVICE_TYPE`

`EXTERNAL_PWA_MANIFEST_URL`

`ENABLE_TITLE_GENERATION`

`LICENSE_KEY`

`SSL_ASSERT_FINGERPRINT`

`ENABLE_COMPRESSION_MIDDLEWARE`

`DEFAULT_PROMPT_SUGGESTIONS`

AIOHTTP Client

`AIOHTTP_CLIENT_TIMEOUT`

`AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST`

`AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST`

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER`

`AIOHTTP_CLIENT_SESSION_SSL`

`AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA`

`AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL`

`REQUESTS_VERIFY`

Directories

`DATA_DIR`