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
DATABASE_TYPE=postgresql
DATABASE_USER=openwebui
DATABASE_PASSWORD=your-password
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=openwebui
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: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
.env
# Application
ENV=prod
PORT=8080
WEBUI_NAME="My Open WebUI"
# Security
WEBUI_SECRET_KEY=<generate-random-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
.env
# 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=<secret>
WEBUI_SESSION_COOKIE_SECURE=true
Development Setup
.env
# 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
Docker Deployment
Deploy with Docker
Kubernetes
Deploy on Kubernetes
Reverse Proxy
Configure reverse proxy
Updating
Update your deployment