How to Use Open WebUI

Open WebUI is the chat interface for the local models you already run - a self-hosted, feature-rich UI that connects to Ollama in roughly one step and gives you a private ChatGPT-style experience. This guide covers the official setup path (Docker), the Ollama connection, your first chat, theme and persona customization, and the real errors people hit - with every command verified against docs.openwebui.com today. It sits on the stack from our Ollama install guide and assumes you have a model already pulled - if not, do that first (10 minutes), then come back.

This is the UI layer for the whole local-AI stack: hardware reality is in our laptop LLM guide, and the directory entry with one-paragraph context is here.

Before you start

• Ollama running - Open WebUI connects to it automatically when both are on the same machine.
• Docker installed (recommended). Docker Desktop on macOS/Windows works; on Linux, Docker Engine.
• Version warning: the :main Docker image is a rolling build, and the project ships major releases roughly weekly. Screens may drift slightly from this guide between releases - the settings paths below are the stable ones.
• Python users: 3.11 or 3.12 only. The official docs state 3.13 is not supported yet.

Step 1: Install Open WebUI

The official quick-start command (all in one):

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 piece does (official flag table):

Then open http://localhost:3000.

No Docker? The pip route (official):

pip install open-webui
open-webui serve

That serves on http://localhost:8080. If open-webui isn’t found, the docs’ fix: python -m open_webui serve.

Step 2: Create your admin account

The first account you create becomes the Administrator - and it’s the only role that can approve further signups (new ones arrive as Pending). The official FAQ is deliberate about this: the signup gate exists to protect instances from casual network exposure, and your account data lives locally. Keep these credentials recoverable - losing the admin account means admin-activation loops for everyone else (there’s a documented password-reset procedure for that).

Two settings areas you’ll use constantly (official settings doc):

• User Settings (avatar → Settings) - your theme, default model, personal system prompt.
• Admin Settings (avatar → Settings → Admin) - instance-wide: connections, features, security. The admin setting is the ceiling; users can only switch things on within it.

Step 3: Connect Ollama

On first start, Open WebUI automatically attempts to connect to a local Ollama - usually nothing to do. Two adjustments matter:

If Ollama runs on the same host as the container, use the special DNS name (a Docker container’s localhost is the container itself - official FAQ):

• Connection URL: http://host.docker.internal:11434

Find the settings: avatar → Settings → Admin Settings → Connections → Ollama → Manage (the wrench icon). From there you can also download models and tweak the connection.

Pull models without leaving the UI: open the model selector, type a model name that isn’t there yet (e.g. gemma4), and Open WebUI offers to download it from Ollama’s library directly - the official docs show this as the fastest path.

Step 4: First chat

1. Select your Ollama model in the model picker at the top.
2. Send a real prompt - something your model can actually answer well.
3. Open a second terminal and confirm the request hit Ollama: ollama ps should show the model loaded with recent activity.

Reasoning models (DeepSeek-R1, Qwen3): if their thinking... /thought> blocks render as raw text instead of a collapsed section, the official fix is to run Ollama with the reasoning parser:

ollama serve --reasoning-parser deepseek_r1

Context-length gotcha (official, high-impact): Open WebUI’s num_ctx advanced parameter overrides the Ollama-side OLLAMA_CONTEXT_LENGTH whenever it’s set - and toggling it on pre-fills 2048, which is tiny. Symptoms: silently truncated answers, blank replies, or raw tool-call JSON when native function calling runs out of token room. Rule: leave num_ctx unset (Ollama’s default applies), or set it explicitly to a realistic value like 8192 when you need long conversations.

Step 5: Customize - theme, personas, task model

Theme (dark mode): User Settings → interface theme - Open WebUI ships light/dark, and the design system auto-adapts to both. This is a per-user setting; the admin can’t force it off.

Personas via system prompts: a persona is just a system prompt attached to the model. The official FAQ frames it perfectly: “The model isn’t ‘aware’ of itself; it’s simply been instructed to claim a specific identity. You can do the same thing in Open WebUI by adding a system prompt to your model configuration.” Edit it per model in the model editor (or per chat). Remember the precedence: model-level settings admins configure in Workspace beat your personal system prompt.

Task Model (cost control): Open WebUI runs background tasks - title generation, auto-tags, RAG query generation - which each cost an API call if you’re on cloud models. Official guidance: set a Task Model (Admin Settings → Experience → Interface → Tasks) to a small cheap or local model. With a pure-Ollama setup this is free either way.

Step 6: Sharing basics

• Models are private by default - the docs state all models must be explicitly shared before other users see them.
• Shared chats get a dedicated dashboard: User Settings → Data Controls → Shared Chats → Manage - search past shared links, re-copy them, or revoke access instantly.
• Multi-user by design: this is worth knowing before you buy a bigger machine - Open WebUI assumes many users from day one (per the settings doc).

How to verify it worked

• http://localhost:3000 (Docker) or :8080 (pip) loads the UI and your account has Administrator privileges
• Admin Settings → Connections lists your Ollama instance and the model picker shows your pulled models
• A chat message produced a real answer, and ollama ps confirmed the model loaded
• Theme toggle changes the UI (User Settings → interface theme)
• A persona/model system prompt changes how the model answers
• docker rm -f open-webui followed by the same docker run command restores all your chats (volume intact - this is the official durability test)

Troubleshooting

openssl rand -hex 32
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="YOUR_HEX_KEY" \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

You did it

• Open WebUI runs at :3000 (Docker) or :8080 (pip) and you’re the admin
• Ollama is connected and models are visible and pullable from the UI
• You had a real chat, and you know where num_ctx can silently cap it
• You set your theme, tried a persona system prompt, and know the precedence
• You know shared-chat revocation and the privacy defaults
• Your setup survives docker rm -f + re-run (volume intact)

Next: keep the stack local with how to pick what fits your laptop RAM, or plug Open WebUI’s native MCP support into the MCP world once you’re comfortable.