Python pip Installation

Install Open WebUI using Python pip

Install and run Open WebUI directly using Python pip for development or lightweight deployments.

Prerequisites

• Python 3.11 or 3.12 (Python 3.13 is not yet supported)
• pip package manager
• Git (for development installation)

Open WebUI requires Python 3.11 or 3.12. Make sure you’re using a compatible version to avoid compatibility issues.

Quick Installation

1. Install Open WebUI

   Install using pip:

   pip install open-webui
   
2. Start the Server

   Run Open WebUI:

   open-webui serve
   

   The server will start on http://localhost:8080

Installation Options

Standard Installation

Basic installation with core dependencies:

pip install open-webui

PostgreSQL Support

Install with PostgreSQL support:

pip install open-webui[postgres]

This includes:

• psycopg2-binary - PostgreSQL adapter
• pgvector - PostgreSQL vector extension

All Optional Dependencies

Install with all optional dependencies:

pip install open-webui[all]

Includes additional packages for:

• Vector databases (Qdrant, Milvus, Pinecone, Weaviate, Elasticsearch, Oracle)
• Cloud storage emulators
• Testing frameworks
• Document processing tools

System Dependencies

Open WebUI requires several system packages. Install them based on your OS:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y \
  git \
  build-essential \
  pandoc \
  gcc \
  netcat-openbsd \
  curl \
  jq \
  python3-dev \
  ffmpeg \
  libsm6 \
  libxext6

macOS

brew install pandoc ffmpeg

Windows

Install the following:

• Pandoc
• FFmpeg
• Microsoft C++ Build Tools

Configuration

Environment Variables

Create a .env file in your working directory:

.env

# Ollama Configuration
OLLAMA_BASE_URL='http://localhost:11434'

# OpenAI Configuration
OPENAI_API_BASE_URL=''
OPENAI_API_KEY=''

# Database Configuration
DATABASE_URL='sqlite:///./data/webui.db'

# Security
WEBUI_SECRET_KEY='your-secret-key-here'

# CORS Settings
CORS_ALLOW_ORIGIN='*'

# Telemetry
SCARF_NO_ANALYTICS=true
DO_NOT_TRACK=true
ANONYMIZED_TELEMETRY=false

Data Directory

By default, Open WebUI stores data in:

• Linux/macOS: ~/.local/share/open-webui/data/
• Windows: %APPDATA%\open-webui\data\

Customize with the DATA_DIR environment variable:

export DATA_DIR=/path/to/data
open-webui serve

Running Open WebUI

Basic Usage

open-webui serve

Custom Port

PORT=3000 open-webui serve

With Environment Variables

OLLAMA_BASE_URL=http://localhost:11434 \
WEBUI_SECRET_KEY=$(openssl rand -base64 32) \
open-webui serve

Production Mode

For production, use a production-grade WSGI server:

pip install gunicorn
gunicorn open_webui.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8080

Development Installation

For development with hot-reload:

1. Clone the Repository

   git clone https://github.com/open-webui/open-webui.git
   cd open-webui
   
2. Install Backend Dependencies

   cd backend
   pip install -r requirements.txt
   
3. Install Frontend Dependencies

   cd ..
   npm install
   
4. Run Development Server

   Backend (in backend/ directory):

   bash start.sh
   

   Frontend (in root directory):

   npm run dev
   

Upgrading

Upgrade to Latest Version

pip install --upgrade open-webui

Upgrade with Dependencies

pip install --upgrade --force-reinstall open-webui

Uninstalling

pip uninstall open-webui

Uninstalling Open WebUI does not remove your data directory. Back up or manually delete it if needed.

Virtual Environment (Recommended)

Use a virtual environment to isolate dependencies:

Using venv

# Create virtual environment
python -m venv open-webui-env

# Activate (Linux/macOS)
source open-webui-env/bin/activate

# Activate (Windows)
open-webui-env\Scripts\activate

# Install Open WebUI
pip install open-webui

# Run
open-webui serve

Using conda

# Create environment
conda create -n open-webui python=3.11

# Activate
conda activate open-webui

# Install
pip install open-webui

# Run
open-webui serve

GPU Support (CUDA)

For CUDA GPU acceleration:

1. Install CUDA Toolkit

   Install NVIDIA CUDA Toolkit for your platform.

2. Install PyTorch with CUDA

   # For CUDA 12.1
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
   
   # For CUDA 11.8
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   
3. Install Open WebUI

   pip install open-webui
   

Apple Silicon (M1/M2) Support

For Apple Silicon Macs, use Metal Performance Shaders (MPS):

# Install with MPS support
pip install open-webui

# PyTorch will automatically use MPS when available
open-webui serve

Troubleshooting

Import Errors

If you encounter import errors, ensure you’re using Python 3.11 or 3.12:

python --version

Permission Errors

Use --user flag to install in user directory:

pip install --user open-webui

Database Errors

If database migrations fail:

# Reset database (WARNING: This deletes all data)
rm -rf ~/.local/share/open-webui/data/webui.db
open-webui serve

Port Already in Use

Change the port:

PORT=8081 open-webui serve

Missing System Dependencies

Ensure all system dependencies are installed (see System Dependencies section above).

Environment-Specific Notes

WSL (Windows Subsystem for Linux)

On WSL, ensure you have the required system packages:

sudo apt-get update
sudo apt-get install -y build-essential python3-dev

Docker Alternative

If pip installation doesn’t work for your environment, consider using Docker deployment instead.

Next Steps

Environment Variables

Configure Open WebUI with environment variables

Docker Deployment

Alternative Docker-based installation

Updating

Keep your installation up-to-date

Configuration

Configure Open WebUI features