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

DATABASE_TYPE=postgresql
DATABASE_USER=openwebui
DATABASE_PASSWORD=your-password
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=openwebui

Or use a connection URL:

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

Getting Started

Core Features

Advanced Features

Integrations

Enterprise

Deployment

Development

Help

​Core Settings

​Application

​Database

​PostgreSQL Example

​AI Model Configuration

​Ollama

​OpenAI

​Model Caching

​Authentication & Security

​Core Authentication

​Admin Account Creation

​Session & Cookies

​Trusted Headers

​OAuth

​SCIM

​RAG & Embeddings

​Embedding Models

​Sentence Transformers

​Whisper (Speech-to-Text)

​Tiktoken

​Redis

​WebSocket

​HTTP Client

​Chat Configuration

​Logging

​Audit Logging

​OpenTelemetry

​Performance

​Uvicorn Workers

​Compression

​User Activity

​Network & CORS

​Features

​User Info Headers

​Session Info Headers

​Tools & Extensions

​PWA

​Groups

​Telemetry

​Docker-Specific

​Example Configurations

​Basic Production Setup

​Scaled Deployment with Redis

​Development Setup

​Next Steps

Docker Deployment

Kubernetes

Reverse Proxy

Updating

Build docs developers (and LLMs) love

Core Settings

Application

Database

PostgreSQL Example

AI Model Configuration

Ollama

OpenAI

Model Caching

Authentication & Security

Core Authentication

Admin Account Creation

Session & Cookies

Trusted Headers

OAuth

SCIM

RAG & Embeddings

Embedding Models

Sentence Transformers

Whisper (Speech-to-Text)

Tiktoken

Redis

WebSocket

HTTP Client

Chat Configuration

Logging

Audit Logging

OpenTelemetry

Performance

Uvicorn Workers

Compression

User Activity

Network & CORS

Features

User Info Headers

Session Info Headers

Tools & Extensions

PWA

Groups

Telemetry

Docker-Specific

Example Configurations

Basic Production Setup

Scaled Deployment with Redis

Development Setup

Next Steps