> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Variables
> Complete reference for Open WebUI environment variables
Configure Open WebUI behavior using environment variables. This reference documents all available configuration options.
## Core Settings
### Application
| Variable | Default | Description |
| -------------------- | ---------------- | ------------------------------------------ |
| `ENV` | `dev` | Environment mode: `dev`, `test`, or `prod` |
| `PORT` | `8080` | Port number for the web server |
| `WEBUI_NAME` | `Open WebUI` | Custom name for your instance |
| `WEBUI_BUILD_HASH` | `dev-build` | Build version identifier |
| `DATA_DIR` | `./backend/data` | Directory for storing application data |
| `FRONTEND_BUILD_DIR` | `./build` | Frontend build files location |
| `STATIC_DIR` | `./static` | Static files directory |
| `ENABLE_SIGNUP` | `true` | Allow new user registration |
| `DEFAULT_USER_ROLE` | `pending` | Default role for new users |
### Database
| Variable | Default | Description |
| --------------------------------- | --------------------------- | ------------------------------------------- |
| `DATABASE_URL` | `sqlite:///./data/webui.db` | Database connection URL |
| `DATABASE_TYPE` | - | Database type: `postgresql`, `sqlite`, etc. |
| `DATABASE_USER` | - | Database username |
| `DATABASE_PASSWORD` | - | Database password |
| `DATABASE_HOST` | - | Database host |
| `DATABASE_PORT` | - | Database port |
| `DATABASE_NAME` | - | Database name |
| `DATABASE_SCHEMA` | - | Database schema (PostgreSQL) |
| `DATABASE_POOL_SIZE` | - | Connection pool size |
| `DATABASE_POOL_MAX_OVERFLOW` | `0` | Max pool overflow connections |
| `DATABASE_POOL_TIMEOUT` | `30` | Pool connection timeout (seconds) |
| `DATABASE_POOL_RECYCLE` | `3600` | Connection recycle time (seconds) |
| `DATABASE_ENABLE_SQLITE_WAL` | `false` | Enable SQLite WAL mode |
| `DATABASE_ENABLE_SESSION_SHARING` | `false` | Reuse database sessions |
| `ENABLE_DB_MIGRATIONS` | `true` | Automatically run database migrations |
| `RESET_CONFIG_ON_START` | `false` | Reset configuration on startup |
### PostgreSQL Example
```bash theme={null}
DATABASE_TYPE=postgresql
DATABASE_USER=openwebui
DATABASE_PASSWORD=your-password
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=openwebui
```
Or use a connection URL:
```bash theme={null}
DATABASE_URL=postgresql://openwebui:password@localhost:5432/openwebui
```
## AI Model Configuration
### Ollama
| Variable | Default | Description |
| ------------------- | --------- | ------------------------- |
| `OLLAMA_BASE_URL` | `/ollama` | Ollama API base URL |
| `USE_OLLAMA_DOCKER` | - | Build with bundled Ollama |
### OpenAI
| Variable | Default | Description |
| --------------------- | ------- | ------------------------------ |
| `OPENAI_API_BASE_URL` | - | OpenAI-compatible API base URL |
| `OPENAI_API_KEY` | - | OpenAI API key |
### Model Caching
| Variable | Default | Description |
| ------------------------------ | ------- | -------------------------------- |
| `MODELS_CACHE_TTL` | `1` | Model list cache TTL (seconds) |
| `ENABLE_CUSTOM_MODEL_FALLBACK` | `false` | Enable custom model fallback |
| `BYPASS_MODEL_ACCESS_CONTROL` | `false` | Bypass model access restrictions |
## Authentication & Security
### Core Authentication
| Variable | Default | Description |
| ------------------------------------- | ------------ | --------------------------------------------- |
| `WEBUI_AUTH` | `true` | Enable authentication (required for security) |
| `WEBUI_SECRET_KEY` | `t0p-s3cr3t` | Secret key for JWT tokens |
| `ENABLE_INITIAL_ADMIN_SIGNUP` | `false` | Allow initial admin signup |
| `ENABLE_SIGNUP_PASSWORD_CONFIRMATION` | `false` | Require password confirmation |
| `ENABLE_PASSWORD_VALIDATION` | `false` | Enable password validation |
| `PASSWORD_VALIDATION_REGEX_PATTERN` | (complex) | Password validation regex |
| `PASSWORD_VALIDATION_HINT` | - | Password requirements hint |
Always set `WEBUI_SECRET_KEY` to a secure random value in production. Generate one with:
```bash theme={null}
openssl rand -base64 32
```
### Admin Account Creation
Create admin account on startup:
| Variable | Default | Description |
| ---------------------- | ------- | ------------------- |
| `WEBUI_ADMIN_EMAIL` | - | Admin email address |
| `WEBUI_ADMIN_PASSWORD` | - | Admin password |
| `WEBUI_ADMIN_NAME` | `Admin` | Admin display name |
### Session & Cookies
| Variable | Default | Description |
| --------------------------------- | --------- | --------------------------------- |
| `WEBUI_SESSION_COOKIE_SAME_SITE` | `lax` | Session cookie SameSite attribute |
| `WEBUI_SESSION_COOKIE_SECURE` | `false` | Session cookie Secure flag |
| `WEBUI_AUTH_COOKIE_SAME_SITE` | (session) | Auth cookie SameSite attribute |
| `WEBUI_AUTH_COOKIE_SECURE` | `false` | Auth cookie Secure flag |
| `WEBUI_AUTH_SIGNOUT_REDIRECT_URL` | - | Redirect URL after signout |
### Trusted Headers
| Variable | Default | Description |
| ---------------------------------- | ------- | -------------------------- |
| `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` | - | Trusted email header name |
| `WEBUI_AUTH_TRUSTED_NAME_HEADER` | - | Trusted name header name |
| `WEBUI_AUTH_TRUSTED_GROUPS_HEADER` | - | Trusted groups header name |
### OAuth
| Variable | Default | Description |
| ------------------------------------ | -------------------- | -------------------------------------- |
| `ENABLE_OAUTH_EMAIL_FALLBACK` | `false` | Use email as fallback for OAuth |
| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | Store ID token in cookie |
| `OAUTH_CLIENT_INFO_ENCRYPTION_KEY` | (WEBUI\_SECRET\_KEY) | Encryption key for OAuth client info |
| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | (WEBUI\_SECRET\_KEY) | Encryption key for OAuth tokens |
| `OAUTH_MAX_SESSIONS_PER_USER` | `10` | Max concurrent OAuth sessions per user |
| `ENABLE_OAUTH_TOKEN_EXCHANGE` | `false` | Allow OAuth token exchange |
### SCIM
| Variable | Default | Description |
| -------------------- | ------- | ----------------------------- |
| `ENABLE_SCIM` | `false` | Enable SCIM 2.0 provisioning |
| `SCIM_TOKEN` | - | SCIM authentication token |
| `SCIM_AUTH_PROVIDER` | - | OAuth provider for SCIM users |
## RAG & Embeddings
### Embedding Models
| Variable | Default | Description |
| ---------------------------- | ---------------------------------------- | --------------------------- |
| `RAG_EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Sentence transformer model |
| `RAG_RERANKING_MODEL` | - | Reranking model |
| `AUXILIARY_EMBEDDING_MODEL` | `TaylorAI/bge-micro-v2` | Auxiliary embedding model |
| `SENTENCE_TRANSFORMERS_HOME` | `./cache/embedding/models` | Model cache directory |
| `RAG_EMBEDDING_TIMEOUT` | - | Embedding operation timeout |
| `RAG_SYSTEM_CONTEXT` | `false` | Use system context for RAG |
### Sentence Transformers
| Variable | Default | Description |
| ----------------------------------------------------------------- | ------- | --------------------------------- |
| `SENTENCE_TRANSFORMERS_BACKEND` | `torch` | Backend for sentence transformers |
| `SENTENCE_TRANSFORMERS_MODEL_KWARGS` | - | Model keyword arguments (JSON) |
| `SENTENCE_TRANSFORMERS_CROSS_ENCODER_BACKEND` | `torch` | Cross-encoder backend |
| `SENTENCE_TRANSFORMERS_CROSS_ENCODER_MODEL_KWARGS` | - | Cross-encoder kwargs (JSON) |
| `SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION` | `true` | Apply sigmoid to reranking scores |
### Whisper (Speech-to-Text)
| Variable | Default | Description |
| ------------------- | ------------------------ | ------------------- |
| `WHISPER_MODEL` | `base` | Whisper model size |
| `WHISPER_MODEL_DIR` | `./cache/whisper/models` | Whisper model cache |
### Tiktoken
| Variable | Default | Description |
| ------------------------ | ------------------ | ------------------------ |
| `TIKTOKEN_ENCODING_NAME` | `cl100k_base` | Tiktoken encoding |
| `TIKTOKEN_CACHE_DIR` | `./cache/tiktoken` | Tiktoken cache directory |
## Redis
| Variable | Default | Description |
| -------------------------------- | ------------ | -------------------------------------- |
| `REDIS_URL` | - | Redis connection URL |
| `REDIS_CLUSTER` | `false` | Use Redis cluster mode |
| `REDIS_KEY_PREFIX` | `open-webui` | Redis key prefix |
| `REDIS_SENTINEL_HOSTS` | - | Redis Sentinel hosts (comma-separated) |
| `REDIS_SENTINEL_PORT` | `26379` | Redis Sentinel port |
| `REDIS_SENTINEL_MAX_RETRY_COUNT` | `2` | Max retries for Sentinel failover |
| `REDIS_SOCKET_CONNECT_TIMEOUT` | - | Socket connection timeout |
| `REDIS_RECONNECT_DELAY` | - | Reconnection delay |
## WebSocket
| Variable | Default | Description |
| ----------------------------------- | ---------------- | ------------------------------- |
| `ENABLE_WEBSOCKET_SUPPORT` | `true` | Enable WebSocket support |
| `WEBSOCKET_MANAGER` | - | WebSocket manager backend |
| `WEBSOCKET_REDIS_URL` | (REDIS\_URL) | Redis URL for WebSocket |
| `WEBSOCKET_REDIS_CLUSTER` | (REDIS\_CLUSTER) | Use Redis cluster for WebSocket |
| `WEBSOCKET_REDIS_OPTIONS` | - | Redis options (JSON) |
| `WEBSOCKET_REDIS_LOCK_TIMEOUT` | `60` | Redis lock timeout |
| `WEBSOCKET_SENTINEL_HOSTS` | - | Sentinel hosts for WebSocket |
| `WEBSOCKET_SENTINEL_PORT` | `26379` | Sentinel port for WebSocket |
| `WEBSOCKET_SERVER_LOGGING` | `false` | Enable WebSocket server logging |
| `WEBSOCKET_SERVER_ENGINEIO_LOGGING` | `false` | Enable Engine.IO logging |
| `WEBSOCKET_SERVER_PING_TIMEOUT` | `20` | WebSocket ping timeout |
| `WEBSOCKET_SERVER_PING_INTERVAL` | `25` | WebSocket ping interval |
## HTTP Client
| Variable | Default | Description |
| ----------------------------------------- | ------- | ------------------------------- |
| `REQUESTS_VERIFY` | `true` | Verify SSL certificates |
| `AIOHTTP_CLIENT_TIMEOUT` | - | Default aiohttp timeout |
| `AIOHTTP_CLIENT_SESSION_SSL` | `true` | Enable SSL for aiohttp |
| `AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST` | `10` | Timeout for model list requests |
| `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA` | `10` | Timeout for tool server data |
| `AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL` | `true` | SSL for tool servers |
## Chat Configuration
| Variable | Default | Description |
| -------------------------------------------------- | ------- | ----------------------------- |
| `ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION` | `false` | Convert base64 images to URLs |
| `CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE` | `1` | Stream delta chunk size |
| `CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES` | `30` | Max tool call retries |
| `CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE` | - | Max buffer size for streaming |
| `ENABLE_REALTIME_CHAT_SAVE` | `false` | Save chats in real-time |
| `ENABLE_QUERIES_CACHE` | `false` | Cache query results |
## Logging
| Variable | Default | Description |
| ------------------ | ------- | ---------------------------------------------------- |
| `GLOBAL_LOG_LEVEL` | `INFO` | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
| `LOG_FORMAT` | - | Log format: `json` for structured logging |
### Audit Logging
| Variable | Default | Description |
| ------------------------------ | ----------------------- | ------------------------------------------------------- |
| `ENABLE_AUDIT_STDOUT` | `false` | Log audit events to stdout |
| `ENABLE_AUDIT_LOGS_FILE` | `true` | Log audit events to file |
| `AUDIT_LOGS_FILE_PATH` | `./data/audit.log` | Audit log file path |
| `AUDIT_LOG_FILE_ROTATION_SIZE` | `10MB` | Log rotation size |
| `AUDIT_UVICORN_LOGGER_NAMES` | `uvicorn.access` | Logger names for audit (comma-separated) |
| `AUDIT_LOG_LEVEL` | `NONE` | Audit level: NONE, METADATA, REQUEST, REQUEST\_RESPONSE |
| `MAX_BODY_LOG_SIZE` | `2048` | Max body size to log (bytes) |
| `AUDIT_EXCLUDED_PATHS` | `/chats,/chat,/folders` | Paths to exclude (comma-separated) |
## OpenTelemetry
| Variable | Default | Description |
| ------------------------------------- | -------------------------------- | ----------------------------------------- |
| `ENABLE_OTEL` | `false` | Enable OpenTelemetry |
| `ENABLE_OTEL_TRACES` | `false` | Enable trace export |
| `ENABLE_OTEL_METRICS` | `false` | Enable metrics export |
| `ENABLE_OTEL_LOGS` | `false` | Enable log export |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP endpoint |
| `OTEL_METRICS_EXPORTER_OTLP_ENDPOINT` | (OTEL\_EXPORTER\_OTLP\_ENDPOINT) | Metrics endpoint |
| `OTEL_LOGS_EXPORTER_OTLP_ENDPOINT` | (OTEL\_EXPORTER\_OTLP\_ENDPOINT) | Logs endpoint |
| `OTEL_EXPORTER_OTLP_INSECURE` | `false` | Use insecure connection |
| `OTEL_SERVICE_NAME` | `open-webui` | Service name |
| `OTEL_RESOURCE_ATTRIBUTES` | - | Resource attributes (key1=val1,key2=val2) |
| `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | Trace sampler |
| `OTEL_OTLP_SPAN_EXPORTER` | `grpc` | Span exporter: `grpc` or `http` |
| `OTEL_BASIC_AUTH_USERNAME` | - | Basic auth username |
| `OTEL_BASIC_AUTH_PASSWORD` | - | Basic auth password |
## Performance
### Uvicorn Workers
| Variable | Default | Description |
| ----------------- | ------- | ---------------------------------- |
| `UVICORN_WORKERS` | `1` | Number of Uvicorn worker processes |
### Compression
| Variable | Default | Description |
| ------------------------------- | ------- | --------------------------- |
| `ENABLE_COMPRESSION_MIDDLEWARE` | `true` | Enable response compression |
### User Activity
| Variable | Default | Description |
| --------------------------------------------- | ------- | --------------------------------- |
| `DATABASE_USER_ACTIVE_STATUS_UPDATE_INTERVAL` | - | Update interval for active status |
| `ENABLE_PUBLIC_ACTIVE_USERS_COUNT` | `true` | Show active user count publicly |
## Network & CORS
| Variable | Default | Description |
| --------------------- | ------- | --------------------------------- |
| `CORS_ALLOW_ORIGIN` | `*` | CORS allowed origins |
| `FORWARDED_ALLOW_IPS` | `*` | Allowed IPs for forwarded headers |
## Features
| Variable | Default | Description |
| ---------------------------------- | ------- | ---------------------------------------------- |
| `ENABLE_VERSION_UPDATE_CHECK` | `true` | Check for updates |
| `OFFLINE_MODE` | `false` | Run in offline mode |
| `SAFE_MODE` | `false` | Enable safe mode |
| `ENABLE_EASTER_EGGS` | `true` | Enable easter eggs |
| `ENABLE_FORWARD_USER_INFO_HEADERS` | `false` | Forward user info in headers |
| `ENABLE_STAR_SESSIONS_MIDDLEWARE` | `false` | Enable star sessions middleware (experimental) |
### User Info Headers
| Variable | Default | Description |
| ------------------------------------- | ------------------------ | ------------------- |
| `FORWARD_USER_INFO_HEADER_USER_NAME` | `X-OpenWebUI-User-Name` | Header for username |
| `FORWARD_USER_INFO_HEADER_USER_ID` | `X-OpenWebUI-User-Id` | Header for user ID |
| `FORWARD_USER_INFO_HEADER_USER_EMAIL` | `X-OpenWebUI-User-Email` | Header for email |
| `FORWARD_USER_INFO_HEADER_USER_ROLE` | `X-OpenWebUI-User-Role` | Header for role |
### Session Info Headers
| Variable | Default | Description |
| ---------------------------------------- | ------------------------ | --------------------- |
| `FORWARD_SESSION_INFO_HEADER_MESSAGE_ID` | `X-OpenWebUI-Message-Id` | Header for message ID |
| `FORWARD_SESSION_INFO_HEADER_CHAT_ID` | `X-OpenWebUI-Chat-Id` | Header for chat ID |
## Tools & Extensions
| Variable | Default | Description |
| --------------------------------------------- | ------- | ---------------------------------- |
| `ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS` | `true` | Allow pip install from frontmatter |
| `PIP_OPTIONS` | - | Additional pip options |
| `PIP_PACKAGE_INDEX_OPTIONS` | - | pip package index options |
## PWA
| Variable | Default | Description |
| --------------------------- | ------- | ------------------------- |
| `EXTERNAL_PWA_MANIFEST_URL` | - | External PWA manifest URL |
## Groups
| Variable | Default | Description |
| -------------------------------- | --------- | ------------------------------------------------------------- |
| `DEFAULT_GROUP_SHARE_PERMISSION` | `members` | Default group share permission: `true`, `false`, or `members` |
## Telemetry
| Variable | Default | Description |
| ---------------------- | ------- | --------------------------- |
| `SCARF_NO_ANALYTICS` | `true` | Disable Scarf analytics |
| `DO_NOT_TRACK` | `true` | Honor Do Not Track |
| `ANONYMIZED_TELEMETRY` | `false` | Enable anonymized telemetry |
## Docker-Specific
These are build-time arguments, not runtime environment variables:
| Build Arg | Default | Description |
| ------------------------------- | ---------------------------------------- | --------------------------------- |
| `USE_CUDA` | `false` | Build with CUDA support |
| `USE_OLLAMA` | `false` | Bundle Ollama in image |
| `USE_SLIM` | `false` | Slim build without models |
| `USE_CUDA_VER` | `cu128` | CUDA version: cu117, cu121, cu128 |
| `USE_EMBEDDING_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model |
| `USE_RERANKING_MODEL` | - | Reranking model |
| `USE_AUXILIARY_EMBEDDING_MODEL` | `TaylorAI/bge-micro-v2` | Auxiliary model |
| `BUILD_HASH` | `dev-build` | Build hash |
| `UID` / `GID` | `0` | User/Group ID |
| `USE_PERMISSION_HARDENING` | `false` | OpenShift permission hardening |
## Example Configurations
### Basic Production Setup
```bash .env theme={null}
# Application
ENV=prod
PORT=8080
WEBUI_NAME="My Open WebUI"
# Security
WEBUI_SECRET_KEY=
WEBUI_SESSION_COOKIE_SECURE=true
WEBUI_AUTH_COOKIE_SECURE=true
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/openwebui
# AI Models
OLLAMA_BASE_URL=http://ollama:11434
OPENAI_API_KEY=sk-...
# CORS
CORS_ALLOW_ORIGIN=https://myapp.com
# Telemetry
SCARF_NO_ANALYTICS=true
DO_NOT_TRACK=true
```
### Scaled Deployment with Redis
```bash .env theme={null}
# Application
UVICORN_WORKERS=4
ENV=prod
# Database
DATABASE_URL=postgresql://user:pass@postgres:5432/openwebui
DATABASE_POOL_SIZE=20
# Redis
REDIS_URL=redis://redis:6379/0
WEBSOCKET_MANAGER=redis
WEBSOCKET_REDIS_URL=redis://redis:6379/0
# Security
WEBUI_SECRET_KEY=
WEBUI_SESSION_COOKIE_SECURE=true
```
### Development Setup
```bash .env theme={null}
# Application
ENV=dev
GLOBAL_LOG_LEVEL=DEBUG
# Database
DATABASE_URL=sqlite:///./data/webui.db
# AI Models
OLLAMA_BASE_URL=http://localhost:11434
# CORS (allow all for development)
CORS_ALLOW_ORIGIN=*
```
## Next Steps
Deploy with Docker
Deploy on Kubernetes
Configure reverse proxy
Update your deployment