Local Development Setup

Set up your local development environment for Open WebUI

Prerequisites

Before setting up Open WebUI for local development, ensure you have the following installed:

• Node.js version 18.13.0 or higher (up to 22.x.x)
• npm version 6.0.0 or higher
• Python version 3.11 or 3.12
• Git

Clone the Repository

First, clone the Open WebUI repository:

git clone https://github.com/open-webui/open-webui.git
cd open-webui

Frontend Setup (SvelteKit)

The frontend is built with SvelteKit and uses Vite as the build tool.

Install Dependencies

npm install

Development Server

Start the frontend development server:

npm run dev

The development server will start at http://localhost:5173 (Vite default) with hot-reload enabled.

Alternative Port

To run on port 5050:

npm run dev:5050

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build for production
• npm run preview - Preview production build
• npm run check - Run Svelte type checking
• npm run lint - Lint frontend, types, and backend
• npm run format - Format code with Prettier

Backend Setup (FastAPI)

The backend is built with FastAPI and Python.

Install Python Dependencies

It’s recommended to use a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies using pip:

pip install -e .

Or install with all optional dependencies:

pip install -e ".[all]"

Run the Backend

Start the FastAPI backend server:

open-webui serve

By default, the backend runs at http://0.0.0.0:8080.

Custom Host and Port

open-webui serve --host 127.0.0.1 --port 3000

Development Mode

For backend development with auto-reload:

open-webui dev

Or use uvicorn directly:

uvicorn open_webui.main:app --reload --host 0.0.0.0 --port 8080

Environment Configuration

Secret Key

Open WebUI requires a secret key for session management. When running via open-webui serve, a key is automatically generated and stored in .webui_secret_key.

For manual configuration:

export WEBUI_SECRET_KEY="your-secret-key-here"

Common Environment Variables

# Ollama Configuration
export OLLAMA_BASE_URL="http://localhost:11434"
export ENABLE_OLLAMA_API=true

# OpenAI Configuration
export OPENAI_API_KEY="your-api-key"
export ENABLE_OPENAI_API=true

# Database
export DATABASE_URL="sqlite:///./webui.db"

# Development
export ENV="dev"

Create a .env file in the project root for persistent configuration.

Database Setup

Open WebUI uses SQLite by default. The database file (webui.db) is created automatically on first run in the backend/data directory.

PostgreSQL (Optional)

For PostgreSQL support:

pip install ".[postgres]"

Set the database URL:

export DATABASE_URL="postgresql://user:password@localhost/openwebui"

Migrations

Database migrations are handled automatically by Alembic and Peewee-migrate when the application starts.

Code Quality Tools

Linting

Frontend:

npm run lint:frontend

Backend:

pylint backend/

Or use the Black formatter:

black . --exclude ".venv/|/venv/"

Type Checking

npm run check

Testing

Frontend tests:

npm run test:frontend

Running with Docker (Development)

For a complete development environment with Docker:

docker compose up --build

This builds and runs both frontend and backend services with volume mounts for live reloading.

Troubleshooting

Port Conflicts

If port 8080 is already in use, specify a different port:

open-webui serve --port 8081

CUDA Support

For CUDA-enabled environments:

export USE_CUDA_DOCKER="true"

Verify CUDA is working:

import torch
print(torch.cuda.is_available())

Database Issues

Delete the database file to start fresh:

rm backend/data/webui.db

Next Steps

• Review the Architecture to understand the system design
• Read the Contributing Guide before submitting changes
• Explore Plugin Development to extend functionality

Additional Resources

• Open WebUI Documentation
• Discord Community
• GitHub Issues