Open WebUI

https://docs.openwebui.com
Admin
Open WebUI is an extensible, self-hosted AI platform designed for offline operation. It supports...
Tokens:370,291
Snippets:5,318
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Setup Open WebUI Frontend

Source: https://docs.openwebui.com/getting-started/advanced-topics/development

Install frontend dependencies, build the frontend, and start the development server. Ensure you are in the project root directory.

```bash
cp -RPp .env.example .env
npm install
npm run build
npm run dev
```

--------------------------------

### Install and Start LiteLLM Proxy

Source: https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible

Quick setup commands to install LiteLLM and start the proxy server on port 4000.

```bash
pip install litellm
litellm --model gpt-4 --port 4000
```

--------------------------------

### Example: Start Llama.cpp Server with Specific Path

Source: https://docs.openwebui.com/tutorials/integrations/llm-providers/deepseekr1-dynamic

An example command to start the Llama.cpp server, demonstrating how to specify the model path when it's downloaded to a particular directory. This command uses '/Users/tim/Documents/workspace' as the base directory for the model files.

```bash
./llama-server \
    --model /Users/tim/Documents/workspace/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \
    --port 10000 \
    --ctx-size 1024 \
    --n-gpu-layers 40
```

--------------------------------

### Install and Run Open WebUI with pip

Source: https://docs.openwebui.com/

Install the package via pip and start the server locally.

```bash
pip install open-webui
open-webui serve
```

--------------------------------

### Start the Open WebUI server

Source: https://docs.openwebui.com/getting-started/quick-start

Launch the application server after installation.

```bash
open-webui serve
```

--------------------------------

### Install and run CPTR

Source: https://docs.openwebui.com/ecosystem/computer/install

The standard commands to install the package and start the service.

```bash
pip install cptr
cptr run
```

--------------------------------

### Setup Open WebUI Backend with venv

Source: https://docs.openwebui.com/getting-started/advanced-topics/development

Navigate to the backend directory, create and activate a Python virtual environment using venv, install backend dependencies, and start the development server.

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -U
sh dev.sh
```

--------------------------------

### Setup Open WebUI Backend with Conda

Source: https://docs.openwebui.com/getting-started/advanced-topics/development

Navigate to the backend directory, create and activate a Conda virtual environment using Python 3.11, install backend dependencies, and start the development server.

```bash
cd backend
conda create --name open-webui python=3.11
conda activate open-webui
pip install -r requirements.txt -U
sh dev.sh
```

--------------------------------

### Install and run cptr in PowerShell

Source: https://docs.openwebui.com/ecosystem/computer/install/windows

Use these commands to install the package and start the service. Ensure Python is configured in your system PATH.

```powershell
py -m pip install cptr
cptr run
```

--------------------------------

### Install and Run with pip

Source: https://docs.openwebui.com/features/chat-conversations/audio/text-to-speech/chatterbox-tts-api-integration

Traditional installation method using Python virtual environments and pip.

```bash

# Clone the repository
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# Setup environment — using Python 3.11
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy and customize environment variables
cp .env.example .env

# Add your voice sample (or use the provided one)

# cp your-voice.mp3 voice-sample.mp3

# Start the API with FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 4123

# Or use the main script
python main.py
```

--------------------------------

### Install and Run Open Terminal MCP Server with pip

Source: https://docs.openwebui.com/features/open-terminal/setup/installation

Install the package with the optional `mcp` extra using pip, then run the MCP server. This is the recommended installation method.

```bash
pip install "open-terminal[mcp]"
```

```bash
open-terminal mcp
```

--------------------------------

### Install mcpo with uvx

Source: https://docs.openwebui.com/features/extensibility/plugin/tools/openapi-servers/mcp

Install the mcpo tool using uvx for faster startup. This command installs mcpo and immediately runs it, forwarding the specified port and executing your MCP server command.

```bash
uvx mcpo --port 8000 -- your_mcp_server_command
```

--------------------------------

### Start SearXNG Server

Source: https://docs.openwebui.com/features/chat-conversations/web-search/providers/searxng

Command to start the SearXNG container.

```bash
docker compose up -d
```

--------------------------------

### Troubleshooting installation

Source: https://docs.openwebui.com/ecosystem/computer/quickstart

Alternative installation command if the standard command is not found in the shell path.

```bash
python -m pip install cptr
```

--------------------------------

### Install Computer with pip

Source: https://docs.openwebui.com/ecosystem/computer/reference/cli

Standard installation command requiring Python 3.10+.

```bash
pip install cptr
```

--------------------------------

### Install Docker on Ubuntu

Source: https://docs.openwebui.com/reference/https/caddy

Use this command to install Docker and its associated plugins on an Ubuntu system.

```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-compose
```

--------------------------------

### Install dependencies

Source: https://docs.openwebui.com/features/extensibility/pipelines

Install the necessary Python packages required for the server to function.

```bash
pip install -r requirements.txt
```

--------------------------------

### Navigating to Installation Directory

Source: https://docs.openwebui.com/troubleshooting/manual-database-migration

Change to the backend directory and activate the virtual environment if applicable.

```bash
# Navigate to Open WebUI installation
cd /path/to/open-webui/backend/open_webui

# Activate virtual environment if used
source ../../venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows
```

--------------------------------

### Complete Redis Configuration Example

Source: https://docs.openwebui.com/tutorials/integrations/redis

Example showing all Redis-related environment variables for multi-worker deployments, WebSocket support, and recommended settings for Sentinel and connection pooling.

```bash
# Required for multi-worker/multi-instance deployments
REDIS_URL="redis://redis:6379/0"

# Required for websocket support
ENABLE_WEBSOCKET_SUPPORT="true"
WEBSOCKET_MANAGER="redis"
WEBSOCKET_REDIS_URL="redis://redis:6379/1"

# Recommended for Sentinel deployments (prevents failover hangs)
REDIS_SOCKET_CONNECT_TIMEOUT=5
REDIS_SENTINEL_MAX_RETRY_COUNT=5
REDIS_RECONNECT_DELAY=1000

# Recommended: detect stale pooled connections (must be < Redis server timeout)
REDIS_HEALTH_CHECK_INTERVAL=60

# Recommended: enable TCP keepalive for dead-peer detection at the kernel level
REDIS_SOCKET_KEEPALIVE=True

# Optional
REDIS_KEY_PREFIX="open-webui"
```

--------------------------------

### Successful Startup Log Output

Source: https://docs.openwebui.com/troubleshooting/manual-database-migration

Example of expected log output upon successful database initialization.

```text
INFO:     [db] Database initialization completeINFO:     [main] Open WebUI starting on http://0.0.0.0:8080
```

--------------------------------

### Install cloudflared as a system service

Source: https://docs.openwebui.com/reference/https/cloudflare-tunnel

Installs and enables `cloudflared` to run as a system service, ensuring the tunnel starts automatically on boot and remains active.

```bash
sudo cloudflared service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
```

--------------------------------

### Install and Run with uv

Source: https://docs.openwebui.com/features/chat-conversations/audio/text-to-speech/chatterbox-tts-api-integration

Recommended method for faster dependency resolution and automated virtual environment management.

```bash

# Clone the repository
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv (automatically creates venv)
uv sync

# Copy and customize environment variables
cp .env.example .env

# Start the API with FastAPI
uv run uvicorn app.main:app --host 0.0.0.0 --port 4123

# Or use the main script
uv run main.py
```

--------------------------------

### Restore Data Directory for Python Install

Source: https://docs.openwebui.com/ecosystem/computer/operate/data-and-backups

Unpacks the backup and starts a test instance on a different port to verify data integrity.

```bash
mkdir -p /tmp/cptr-restore
tar -C /tmp/cptr-restore -xzf cptr-data-backup.tgz
CPTR_DATA_DIR=/tmp/cptr-restore/.cptr cptr run --port 8001
```

--------------------------------

### Install and Run Open WebUI with uv

Source: https://docs.openwebui.com/

Install the uv package manager and run Open WebUI using uvx.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve
```

--------------------------------

### Start Time Server Locally

Source: https://docs.openwebui.com/features/extensibility/plugin/tools/openapi-servers/open-webui

Clone the openapi-servers repository, navigate to the time server directory, install dependencies, and run the server using uvicorn. This hosts a local OpenAPI server at http://localhost:8000.

```bash
git clone https://github.com/open-webui/openapi-servers
cd openapi-servers
cd servers/time
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --reload
```

--------------------------------

### Basic .oikb.yaml Configuration

Source: https://docs.openwebui.com/ecosystem/knowledge-base-sync/daemon

Example `.oikb.yaml` file demonstrating default settings and configuration for two sources: 'wiki' from GitHub and 'handbook' from Confluence.

```yaml
defaults:
  interval: 1h
  concurrency: 4
  filter:
    max-size: 50mb

sources:
  - name: wiki
    source: github:owner/repo
    kb-id: 8f3a2b1c-...
    webhook: true

  - name: handbook
    source: confluence:ENG
    kb-id: 4e7d9a0f-...
    interval: "0 6 * * 1-5"
    notify:
      url: https://hooks.slack.com/services/T.../B.../xxx
      on: error
```

--------------------------------

### Install and Run Open WebUI with Ollama

Source: https://docs.openwebui.com/alternatives/ollama

This command pulls the Llama3 model and then runs Open WebUI in a Docker container, mapping the necessary ports and volumes. It's the most common setup for using Open WebUI with Ollama.

```bash
ollama pull llama3
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data --name open-webui \
  ghcr.io/open-webui/open-webui:main
```

--------------------------------

### Add Open Terminal to Docker Compose

Source: https://docs.openwebui.com/features/open-terminal/setup/installation

Integrates Open Terminal as a service within an existing Docker Compose setup. This example shows how to define the Open Terminal service, its image, container name, volumes, and environment variables.

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data

  open-terminal:
    image: ghcr.io/open-webui/open-terminal
    container_name: open-terminal
    volumes:
      - open-terminal:/home/user
    environment:
      - OPEN_TERMINAL_API_KEY=your-secret-key

volumes:
  open-webui:
  open-terminal:
```

--------------------------------

### Start the pod

Source: https://docs.openwebui.com/getting-started/quick-start

Command to initiate the deployment using the specified YAML file.

```bash
podman kube play ./play.yaml
```

--------------------------------

### Install ngrok using Chocolatey

Source: https://docs.openwebui.com/reference/https/ngrok

Use this command to install ngrok on Windows if you have Chocolatey installed.

```powershell
choco install ngrok
```

--------------------------------

### Install ngrok using Homebrew

Source: https://docs.openwebui.com/reference/https/ngrok

Use this command to install ngrok on macOS or Linux if you have Homebrew installed.

```bash
brew install ngrok
```

--------------------------------

### Configure .env File

Source: https://docs.openwebui.com/features/chat-conversations/web-search/providers/searxng

Example configuration for the .env file to set the hostname.

```bash

# By default listen on https://localhost

# To change this:

# * uncomment SEARXNG_HOSTNAME, and replace <host> by the SearXNG hostname

# * uncomment LETSENCRYPT_EMAIL, and replace <email> by your email (require to create a Let's Encrypt certificate)

SEARXNG_HOSTNAME=localhost

# LETSENCRYPT_EMAIL=<email>

# Optional:

# If you run a very small or a very large instance, you might want to change the amount of used uwsgi workers and threads per worker

# More workers (= processes) means that more search requests can be handled at the same time, but it also causes more resource usage

# SEARXNG_UWSGI_WORKERS=4

# SEARXNG_UWSGI_THREADS=4
```

--------------------------------

### Install Tailscale using the official script

Source: https://docs.openwebui.com/reference/https/tailscale

Installs Tailscale on Linux by downloading and executing the official installation script.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
```

--------------------------------

### Install Dependencies and Run Filesystem Server

Source: https://docs.openwebui.com/features/extensibility/plugin/tools/openapi-servers

Install dependencies for the 'filesystem' server and run it using uvicorn. The server will be reachable at http://localhost:8000.

```bash
# Example: Installing dependencies for a specific server 'filesystem'
cd servers/filesystem
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --reload
```

--------------------------------

### Install OpenClaw Agent

Source: https://docs.openwebui.com/getting-started/quick-start/connect-an-agent/openclaw

Install OpenClaw using a shell script or npm. Ensure Node.js 22+ is installed.

```bash
# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash
```

```powershell
# Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex
```

```bash
npm install -g openclaw@latest
```

--------------------------------

### Install and Run Open Terminal with pip

Source: https://docs.openwebui.com/features/open-terminal/setup/installation

Installs the open-terminal package using pip and then runs the server. This method provides a persistent installation on your system.

```bash
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key
```

--------------------------------

### Start the development server

Source: https://docs.openwebui.com/ecosystem/computer/use-cases/test-on-a-real-device

Run the standard development server command in the project workspace terminal.

```bash
npm run dev
```

--------------------------------

### Install mcpo with pip

Source: https://docs.openwebui.com/features/extensibility/plugin/tools/openapi-servers/mcp

Install the mcpo tool using pip. After installation, you can run the mcpo command with the desired port and your MCP server command.

```bash
pip install mcpo
mcpo --port 8000 -- your_mcp_server_command
```

--------------------------------

### Install oikb with Optional Connectors

Source: https://docs.openwebui.com/ecosystem/knowledge-base-sync

Install oikb with specific optional connectors for cloud storage services or all connectors at once.

```bash
pip install oikb[s3]       # Amazon S3
```

```bash
pip install oikb[gcs]      # Google Cloud Storage
```

```bash
pip install oikb[azure]    # Azure Blob
```

```bash
pip install oikb[dropbox]  # Dropbox
```

```bash
pip install oikb[gdrive]   # Google Drive
```

```bash
pip install oikb[all]      # every optional connector at once
```

--------------------------------

### Test Application Startup

Source: https://docs.openwebui.com/troubleshooting/manual-database-migration

Commands to restart the application and monitor logs for successful initialization.

```bash
# Exit the diagnostic container
exit

# Start Open WebUI normally
docker start open-webui

# Watch logs for migration confirmation
docker logs -f open-webui

# Look for successful startup, then test in browser
# Navigate to http://localhost:8080 and verify login page loads
```

```bash
# Start Open WebUI
python -m open_webui.main

# Watch for successful startup messages
# Test by navigating to http://localhost:8080
```

--------------------------------

### Create Admin Account via Environment Variables

Source: https://docs.openwebui.com/getting-started/advanced-topics/hardening

Automates the creation of an initial administrator account during startup if no users exist in the database.

```text
WEBUI_ADMIN_EMAIL=admin@yourcompany.com
WEBUI_ADMIN_PASSWORD=your-strong-password
WEBUI_ADMIN_NAME=Admin
```

--------------------------------

### Run Open Terminal MCP Server without Installation

Source: https://docs.openwebui.com/features/open-terminal/setup/installation

Use this command to run the MCP server without globally installing the package. Ensure `uvx` is installed.

```bash
uvx --from "open-terminal[mcp]" open-terminal mcp
```

--------------------------------

### Install NVIDIA Container Toolkit

Source: https://docs.openwebui.com/features/chat-conversations/audio/text-to-speech/Kokoro-FastAPI-integration

Install the NVIDIA Container Toolkit on Ubuntu/Debian systems to enable GPU support for Docker containers. Restart the Docker service after installation.

```bash
# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

--------------------------------

### Create configuration directory

Source: https://docs.openwebui.com/getting-started/quick-start

Initializes the directory required for rootless Podman Quadlet files.

```bash
mkdir -p ~/.config/containers/systemd/
```

--------------------------------

### Install Open WebUI with pip

Source: https://docs.openwebui.com/getting-started/quick-start

Install the package directly into the Python environment.

```bash
pip install open-webui
```

--------------------------------

### Docker Run Example with Redis Configuration

Source: https://docs.openwebui.com/tutorials/integrations/redis

Example of running Open WebUI via Docker, connecting to Redis within the same Docker network. Use container names for service discovery.

```bash
docker run -d \
  --name open-webui \
  --network openwebui-network \
  -v open-webui:/app/backend/data \
  -p 3000:8080 \
  -e REDIS_URL="redis://redis:6379/0" \
  -e ENABLE_WEBSOCKET_SUPPORT="true" \
  -e WEBSOCKET_MANAGER="redis" \
  -e WEBSOCKET_REDIS_URL="redis://redis:6379/1" \
  -e REDIS_KEY_PREFIX="open-webui" \
  ghcr.io/open-webui/open-webui:main
```

--------------------------------

### Verify OpenSSL Installation

Source: https://docs.openwebui.com/reference/https/nginx

Check if OpenSSL is installed and accessible in the command prompt.

```bash
openssl version
```

--------------------------------

### Start llama.cpp Server

Source: https://docs.openwebui.com/alternatives/llama-cpp

Start the llama.cpp server with a specified model and port. Ensure the model file exists and the port is available.

```bash
llama-server -m your-model.gguf --port 8081
```

--------------------------------

### Install cloudflared on macOS

Source: https://docs.openwebui.com/reference/https/cloudflare-tunnel

Installs the `cloudflared` command-line tool using Homebrew.

```bash
brew install cloudflared
```

--------------------------------

### Handle System Startup and Shutdown Events

Source: https://docs.openwebui.com/features/extensibility/plugin/functions/event

Use system lifecycle events to perform setup tasks like configuration application or teardown tasks like flushing buffers.

```python
async def event(self, event: dict, __event_name__: str = None, __app__=None, **kwargs):
    if __event_name__ == "system.startup.completed":
# Apply a saved configuration, warm a cache, register routes, etc.
        ...
    elif __event_name__ == "system.shutdown.started":
# Flush buffers, close connections, etc.
        ...
```

--------------------------------

### Setting API Key and Running Daemon

Source: https://docs.openwebui.com/ecosystem/knowledge-base-sync/daemon

Demonstrates how to set the OIKB_API_KEY environment variable and start the daemon. This protects sensitive API endpoints.

```bash
export OIKB_API_KEY=your-secret-key
oikb daemon
```

--------------------------------

### Start Nginx Service

Source: https://docs.openwebui.com/reference/https/nginx

Command to start the Nginx container in detached mode.

```bash
docker compose up -d nginx
```

--------------------------------

### Time Input Type Example

Source: https://docs.openwebui.com/features/workspace/prompts

Example of a time picker input field.

```markdown
{{meeting_time | time}}
```
Tokens:
Raw