Open WebUI Setup Guide: Local ChatGPT with Ollama

Open WebUI is a free, self-hosted ChatGPT alternative with 126,000+ GitHub stars that gives you a polished chat interface for local AI models. Install it in one command: 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. It supports RAG, voice, multi-user accounts, and works with any Ollama model.

What Is Open WebUI?

Open WebUI is the most popular self-hosted AI chat interface, providing a polished ChatGPT-like experience for local models running through Ollama. It is the default recommendation in virtually every "run AI locally" tutorial, and for good reason: it works out of the box, looks professional, and packs features that rival commercial platforms.

Open WebUI at a Glance

Why Open WebUI Over CLI?

Running ollama run llama3.2 in a terminal works, but Open WebUI gives you:

1. Conversation history — All chats saved and searchable
2. Multi-model switching — Jump between models mid-conversation
3. Document upload (RAG) — Ask questions about your PDFs and files
4. Voice input/output — Talk to your AI hands-free
5. Image generation — Connect AUTOMATIC1111 or ComfyUI
6. Web search — Pull live information into responses
7. Multi-user accounts — Share one server with your team or family
8. Model management — Pull, delete, and create models from the UI
9. Custom system prompts — Save personas and reuse them
10. API access — OpenAI-compatible API for integrations

---

Prerequisites

Before installing Open WebUI, you need two things:

1. Docker Desktop

Open WebUI runs as a Docker container. Install Docker Desktop for your platform:

• macOS: Download from docker.com or brew install --cask docker
• Windows: Download Docker Desktop from docker.com (requires WSL2)
• Linux: Install Docker Engine:

# Ubuntu/Debian
sudo apt update && sudo apt install docker.io docker-compose-v2
sudo usermod -aG docker $USER
# Log out and back in for group changes

Verify Docker is running:

docker --version
# Docker version 27.x.x

2. Ollama

Open WebUI connects to Ollama for running local models. If you haven't installed it:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows — download installer from ollama.com

Start Ollama and pull a model:

ollama serve  # Start the Ollama server (runs on port 11434)
ollama pull llama3.2  # 2GB download, great starter model

For a detailed Ollama installation walkthrough, see our Ollama Windows installation guide or Mac local AI setup guide.

---

Installation: Docker (Recommended)

Standard Setup — Ollama on Same Machine

This is the most common setup. Open WebUI runs in Docker and connects to Ollama running on your host machine:

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

What each flag does:

Bundled Setup — Ollama Inside Docker

If you want everything in one container (no separate Ollama install needed):

docker run -d -p 3000:8080 \
  --gpus all \
  -v ollama:/root/.ollama \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:ollama

Note: The :ollama tag bundles Ollama inside the container. Use --gpus all for NVIDIA GPU passthrough (requires NVIDIA Container Toolkit on Linux).

Remote Ollama Setup

Connect to Ollama running on another machine on your network:

docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://192.168.1.100:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

On the remote machine, ensure Ollama allows external connections:

# On the Ollama host machine
OLLAMA_HOST=0.0.0.0 ollama serve

Verify Installation

# Check container is running
docker ps

# Should show:
# CONTAINER ID  IMAGE                              STATUS         PORTS
# abc123        ghcr.io/open-webui/open-webui:main Up 2 minutes   0.0.0.0:3000->8080/tcp

# View logs if needed
docker logs open-webui

Open your browser to http://localhost:3000. You should see the Open WebUI login screen.

---

Installation: pip (Alternative)

If you prefer not to use Docker:

# Requires Python 3.11+
pip install open-webui

# Start the server
open-webui serve
# Server starts on http://localhost:8080

The pip install is simpler but has caveats:

• You manage Python dependencies yourself
• Updates require pip install --upgrade open-webui
• Less isolation than Docker
• Good for development and testing

---

First-Time Setup

Step 1: Create Your Admin Account

When you first open http://localhost:3000, you'll see a sign-up form. The first account you create automatically becomes the administrator. Choose a strong password — this account controls all settings.

Step 2: Verify Ollama Connection

After logging in:

1. Click the model dropdown at the top of the chat
2. You should see your Ollama models listed (e.g., llama3.2)
3. If no models appear, check Admin → Settings → Connections

If Ollama is not detected:

• Ensure Ollama is running (ollama serve)
• Verify the connection URL in Settings (default: http://host.docker.internal:11434 for Docker, http://localhost:11434 for pip)

Step 3: Pull Additional Models

You can pull models directly from the Open WebUI interface:

1. Go to Admin → Settings → Models
2. Enter a model name (e.g., qwen2.5:7b) and click Pull
3. Or continue using the terminal: ollama pull qwen2.5:7b

Recommended starter models by hardware:

For a detailed model comparison, see our guide to the best local AI models for 8GB RAM.

Step 4: Start Chatting

Select a model from the dropdown and start typing. Open WebUI supports:

• Markdown rendering in responses
• Code syntax highlighting with copy buttons
• LaTeX math rendering
• Conversation branching — edit and regenerate from any message
• System prompts — set custom instructions per chat

---

Key Features Deep Dive

RAG: Chat with Your Documents

Open WebUI's built-in RAG (Retrieval-Augmented Generation) lets you upload documents and ask questions about them.

How to use RAG:

1. In any chat, click the + button or drag-and-drop files
2. Supported formats: PDF, TXT, DOCX, CSV, MD, HTML, EPUB
3. Open WebUI chunks the document, generates embeddings, and stores them locally
4. Ask questions — the AI retrieves relevant sections automatically

Configure embeddings for better accuracy:

1. Pull an embedding model: ollama pull nomic-embed-text
2. Go to Admin → Settings → Documents
3. Set the embedding model to nomic-embed-text
4. Adjust chunk size (default 1500 tokens works well for most documents)

Create Knowledge Bases:

For recurring reference documents (company docs, codebases, research papers):

1. Go to Workspace → Knowledge
2. Create a new collection
3. Upload multiple files — they're indexed together
4. Reference the collection in any chat with #collection-name

Web Search Integration

Enable web search to give your local AI access to current information:

1. Go to Admin → Settings → Web Search
2. Choose a search provider:
   • SearXNG (self-hosted, private — recommended)
   • Google PSE (requires API key)
   • Brave Search (requires API key)
   • DuckDuckGo (no key needed, rate-limited)
3. Toggle on web search in your chat with the globe icon

Voice Input and Output

Open WebUI supports speech-to-text and text-to-speech:

• Speech-to-Text: Click the microphone icon to dictate. Uses your browser's Web Speech API by default, or configure Whisper (local) for better accuracy
• Text-to-Speech: Enable in Settings → Audio. Responses are read aloud using browser TTS or a configured TTS engine

Image Generation

Connect a local image generation backend:

1. Go to Admin → Settings → Images
2. Set the engine to AUTOMATIC1111 or ComfyUI
3. Enter the API URL (e.g., http://localhost:7860 for AUTOMATIC1111)
4. Generate images directly in chat by asking the AI to create images

Custom Modelfiles

Create specialized personas with custom system prompts and parameters:

1. Go to Workspace → Modelfiles
2. Click Create New
3. Set a name, system prompt, and base model
4. Example: Create a "Code Reviewer" persona using qwen2.5-coder:7b with instructions to focus on bugs, security, and performance

Pipelines and Functions

Open WebUI supports custom Python functions that run alongside your AI:

• Filters — Modify messages before/after they reach the model
• Actions — Add custom buttons to the chat interface
• Pipes — Connect external APIs or custom logic

Install community pipelines from the admin panel or write your own in Python.

---

Docker Compose Setup (Production)

For a more manageable setup, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: always

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - open-webui_data:/app/backend/data
    depends_on:
      - ollama
    restart: always

volumes:
  ollama_data:
  open-webui_data:

Start everything:

docker compose up -d

This setup runs Ollama and Open WebUI as separate containers with proper networking, GPU passthrough, and persistent storage.

---

Administration and Multi-User Setup

User Management

As admin, you control who can access your Open WebUI instance:

1. Admin → Settings → General:

   • Enable/disable new user registration
   • Set default user role (user or pending approval)
   • Configure session timeout

2. Admin → Users:

   • View all registered users
   • Change user roles (admin, user)
   • Delete accounts

Security Best Practices

If exposing Open WebUI beyond localhost:

1. Use a reverse proxy (Nginx, Caddy, Traefik) with HTTPS
2. Disable registration after creating accounts
3. Set a strong admin password
4. Use a firewall to restrict access by IP if on a local network

Example Nginx reverse proxy config:

server {
    listen 443 ssl;
    server_name ai.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

---

Hardware Requirements

Open WebUI itself is very lightweight. The heavy lifting is done by Ollama and your AI models.

Minimum Requirements

Performance by Hardware Tier

For detailed GPU comparisons, see our best GPUs for AI guide and VRAM requirements guide.

---

Updating Open WebUI

Docker Update

# Pull the latest image
docker pull ghcr.io/open-webui/open-webui:main

# Stop and remove the old container
docker stop open-webui
docker rm open-webui

# Re-run with the same command you used originally
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Your chats, settings, and uploads are preserved in the open-webui Docker volume.

Docker Compose Update

docker compose pull
docker compose up -d

pip Update

pip install --upgrade open-webui
open-webui serve

---

Troubleshooting

"Cannot connect to Ollama"

This is the most common issue. Fix it step by step:

# 1. Verify Ollama is running
ollama serve
# or: curl http://localhost:11434/api/version

# 2. Check if Docker can reach the host
docker exec open-webui curl http://host.docker.internal:11434/api/version

# 3. If using Linux, the host.docker.internal alias may not work.
# Use your machine's IP instead:
docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://172.17.0.1:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

Models Not Showing Up

# Verify models are installed
ollama list

# Pull a model if none exist
ollama pull llama3.2

# Refresh models in Open WebUI
# Click the refresh icon next to the model dropdown

Slow Response Times

1. Check GPU usage: ollama ps — verify model is on GPU, not CPU
2. Use a smaller model: Switch from 32B to 8B for faster responses
3. Increase Docker memory: Docker Desktop → Settings → Resources → increase RAM
4. Close other GPU apps: Games, video editors, and other AI tools compete for VRAM

Container Won't Start

# Check logs for errors
docker logs open-webui

# Common fix: port conflict
# Change 3000 to another port if already in use
docker run -d -p 8080:8080 ...

# Reset everything (WARNING: deletes all data)
# docker volume rm open-webui

RAG Not Working

1. Verify an embedding model is set: Admin → Settings → Documents
2. Pull the embedding model: ollama pull nomic-embed-text
3. Re-upload documents after changing the embedding model
4. Check file format is supported (PDF, TXT, DOCX, CSV, MD)

---

Open WebUI vs Alternatives

When to Choose Open WebUI

• You want a ChatGPT-like web interface for local AI
• You need multi-user access for a team or family
• You want RAG (document chat) without extra setup
• You prefer Docker-based deployment
• You want the largest community and fastest development

When to Choose Alternatives

• Jan: Simpler desktop app, no Docker needed — see our Jan vs LM Studio vs Ollama comparison
• LM Studio: Integrated model downloading + inference (no Ollama needed)
• AnythingLLM: Advanced RAG with workspace management — see our AnythingLLM setup guide

---

Environment Variables Reference

Customize Open WebUI behavior with environment variables (pass with -e in Docker):

---

Key Takeaways

1. Open WebUI is the #1 local AI interface — 126K+ GitHub stars, MIT license, active development
2. One Docker command gets you a full ChatGPT-like experience with local models
3. RAG, voice, web search, image generation — all built in, no plugins needed
4. Multi-user support makes it ideal for teams, families, and self-hosted deployments
5. Works with any Ollama model plus OpenAI-compatible APIs
6. Lightweight frontend — the hardware requirements are driven by your AI models, not Open WebUI itself
7. Active community — weekly releases, 400+ contributors, extensive documentation

---

Next Steps

1. Choose the best local AI models for your hardware
2. Set up RAG with local models for document-powered AI
3. Compare Jan vs LM Studio vs Ollama for alternatives
4. Install Continue.dev for AI coding alongside Open WebUI
5. Check VRAM requirements to pick the right model size

---

Open WebUI transforms local AI from a command-line experiment into a polished, daily-driver experience. Whether you're running a single model on a laptop or serving a team from a GPU workstation, Open WebUI provides the interface that makes local AI practical and enjoyable.