> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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

```bash theme={null}
npm install
```

### Development Server

Start the frontend development server:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

Install dependencies using pip:

```bash theme={null}
pip install -e .
```

Or install with all optional dependencies:

```bash theme={null}
pip install -e ".[all]"
```

### Run the Backend

Start the FastAPI backend server:

```bash theme={null}
open-webui serve
```

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

#### Custom Host and Port

```bash theme={null}
open-webui serve --host 127.0.0.1 --port 3000
```

### Development Mode

For backend development with auto-reload:

```bash theme={null}
open-webui dev
```

Or use uvicorn directly:

```bash theme={null}
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:

```bash theme={null}
export WEBUI_SECRET_KEY="your-secret-key-here"
```

### Common Environment Variables

```bash theme={null}
# 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:

```bash theme={null}
pip install ".[postgres]"
```

Set the database URL:

```bash theme={null}
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:**

```bash theme={null}
npm run lint:frontend
```

**Backend:**

```bash theme={null}
pylint backend/
```

Or use the Black formatter:

```bash theme={null}
black . --exclude ".venv/|/venv/"
```

### Type Checking

```bash theme={null}
npm run check
```

### Testing

**Frontend tests:**

```bash theme={null}
npm run test:frontend
```

## Running with Docker (Development)

For a complete development environment with Docker:

```bash theme={null}
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:

```bash theme={null}
open-webui serve --port 8081
```

### CUDA Support

For CUDA-enabled environments:

```bash theme={null}
export USE_CUDA_DOCKER="true"
```

Verify CUDA is working:

```python theme={null}
import torch
print(torch.cuda.is_available())
```

### Database Issues

Delete the database file to start fresh:

```bash theme={null}
rm backend/data/webui.db
```

## Next Steps

* Review the [Architecture](/development/architecture) to understand the system design
* Read the [Contributing Guide](/development/contributing) before submitting changes
* Explore [Plugin Development](/development/plugin-development) to extend functionality

## Additional Resources

* [Open WebUI Documentation](https://docs.openwebui.com)
* [Discord Community](https://discord.gg/5rJgQTnV4s)
* [GitHub Issues](https://github.com/open-webui/open-webui/issues)