Open WebUI is the most-used web interface in the ollama ecosystem (GitHub 150k+ stars). It solves "models exist, but you only have a CLI": it turns local ollama into a ChatGPT-style web UI — multi-user accounts, sessions, model switching, local RAG, web search.

Use it when:

• You already run ollama (or want cloud models) and need a web UI for yourself or a team;
• You want local knowledge-base Q&A (upload documents, then ask) — see combo combo-local-rag (ollama + open-webui is one path);
• You are building a local LLM environment — see combo combo-local-llm-finetune (open-webui is the default UI).

Don't use it when: you only need CLI model calls (direct curl against ollama is lighter); you want a minimal UI without Docker (pip requires Python 3.11~3.12, see below).

China network reality: pull the Docker image via a ghcr mirror (ghcr.nju.edu.cn measured working); the pip form requires Python 3.11~3.12 for all versions — Python 3.14 measured refused.

One command to start the container (measured China path: ghcr.nju.edu.cn prefix + volume):

# Source: Trove detailed guide · verified 2026-09-01
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.nju.edu.cn/open-webui/open-webui:main

Expected output: a container ID; docker ps shows open-webui Up (healthy after ~1-2 minutes)

Open http://localhost:3000 — the first visit asks you to register an admin account (first user is admin automatically).

Prerequisites:

• Docker installed (Docker 29.1.3 in this environment);
• RAM ≥ 4GB (8GB+ recommended; model inference is extra);
• Disk ≥ 10GB free; first image pull ~1.8GB (2026-08-30 combo path measured 7.16GB with multi-layer transfer).

Confirm:

• docker ps shows healthy (brief unhealthy is normal; init takes 1-2 minutes);
• http://localhost:3000 shows the login/register page;
• registering the first account enters the main UI.

Install variants (deep dive)

Open WebUI is a Python app (FastAPI + uvicorn + SQLite) with two forms:

• Docker image form: the image bundles all dependencies and the data dir (/app/backend/data); one docker run starts it. Recommended — because the image can be pulled through ghcr mirrors.
• pip form: pip install open-webui runs on the system Python. All versions require Python 3.11~3.12 (Requires-Python <3.13.0a1,>=3.11, measured 2026-09-01). Ubuntu 24.04's default Python 3.12 works; manually installed 3.13/3.14 is refused by pip — the most common "can't install" cause.

Two key mechanisms:

• OLLAMA_BASE_URL (or the UI "connection settings"): open-webui does not run models itself; it calls ollama's API through this address (default http://localhost:11434). In Docker form, reaching host ollama from the container needs host.docker.internal or the host subnet address (measured 172.17.0.1).
• Data lives in webui.db (SQLite) + uploads/ + vector_db/: accounts, sessions, uploaded documents, RAG vector store. In Docker form you must mount a volume; deleting the container does not lose data.

Where it writes: Docker volume (data dir); pip form = Python package (site-packages) + data dir (default ~/.open-webui/). Port 8080 (in container), host mapping is your choice (example 3000).

Step 1: first open + register admin

Explanation: the first registered user is admin automatically; later users are managed by admin.

# Source: Trove detailed guide · verified 2026-09-01
docker ps --filter name=open-webui

Expected output: container Up (healthy; measured 2026-09-01: ~1-2 minutes from unhealthy to healthy)

Browser → http://localhost:3000 → register with email/password → main UI.

If stuck:

• container stays unhealthy → wait 1-2 minutes (slow init is normal); otherwise check docker logs open-webui tail;
• port busy → change the mapping (-p 3001:8080);
• white screen after register → hard refresh; confirm port 3000 is reachable (not blocked by a proxy).

Step 2: connect ollama (auto + manual)

Explanation: open-webui auto-probes localhost:11434; in Docker form the container's localhost is the container itself — point it at the host.

# Source: Trove detailed guide · verified 2026-09-01
curl -s http://localhost:3000/api/models

Expected output: model list JSON (shows ollama models once connected; measured 2026-09-01: after signin /api/models shows ollama models)

If stuck:

• no models → UI "Settings → Connection": set OLLAMA_BASE_URL to http://172.17.0.1:11434 (container→host); snap ollama also needs sudo snap set ollama host=0.0.0.0:11434 + restart (see ollama detailed guide section 4);
• empty model list but ollama has models → confirm ollama serve is running and base_url is reachable (curl 172.17.0.1:11434/api/version inside the container).

Step 3: web chat & model switching

Explanation: pick a model in the top-right, type and chat; sessions live in the left sidebar.

# Source: Trove detailed guide · verified 2026-09-01
curl -s http://localhost:3000/api/health

Expected output: health OK ({"status":true} shape; /health 200 measured 2026-09-01)

If stuck:

• slow/no reply → check ollama side (ollama ps to confirm the model is loaded); first load of a small model can be slow;
• model missing → connection settings per step 2.

Step 4: call the OpenAI-compatible API from CLI

Explanation: open-webui exposes /api/chat (needs a token; measured 2026-09-01: signin → token → /api/models works).

# Source: Trove detailed guide · verified 2026-09-01
# sign in to get a token (example; use your admin account)
curl -s -X POST http://localhost:3000/api/auths/signin -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpass"}' | python3 -c "import sys,json;print(json.load(sys.stdin)["token"])"

Expected output: a JWT token (signin measured 2026-09-01; later requests send Authorization: Bearer <token>)

If stuck:

• signin fails → confirm the account was registered; check password case;
• 403 → token expired/invalid, sign in again.

Same source as the tool-page matrix; full pairs, states and evidence on the conflict matrix. Known relations:

• open-webui × ollama = compatible (verified): full-chain test 2026-09-01 (container → host ollama inference OK, /api/models shows models);
• open-webui × MaxKB: alternative choices for RAG scenarios (combo-local-rag uses MaxKB as default; open-webui can also do RAG), no conflict;
• Other 26 tools: static judgment possible-compatible (non-overlapping write surfaces).

• Symptom: pip install open-webui "Could not find a version" → Python must be 3.11~3.12 (3.13/3.14 refused, measured); use Docker form
• Symptom: container unhealthy repeatedly → 1-2 minutes init is normal; check docker logs tail
• Symptom: no models in UI → OLLAMA_BASE_URL to 172.17.0.1:11434 (container); snap ollama needs host=0.0.0.0
• Symptom: image won't pull → switch ghcr.nju.edu.cn to another ghcr mirror (ghcr.dockerproxy.com) or retry in a proxy window
• Symptom: data gone after deleting container → must mount the volume (-v open-webui:/app/backend/data); all data lives in the volume

Full four-section entries (symptom→cause→fix→evidence): site docs (if recorded)

# Source: Trove detailed guide · verified 2026-09-01
docker stop open-webui && docker rm open-webui
docker volume rm open-webui

Expected output: container stopped/removed; after volume removal docker volume ls no longer shows open-webui

Note: deleting the volume removes accounts/sessions/documents/RAG vector store. To keep data, remove only the container and keep the volume (re-running reuses it).

• Q: Why can't pip install it? A: all versions require Python 3.11~3.12; Python 3.13/3.14 measured refused. Use the Docker form instead (recommended).
• Q: Can't reach ollama from the container? A: localhost inside the container is the container itself. Set OLLAMA_BASE_URL to http://172.17.0.1:11434 (or host.docker.internal); snap ollama needs host=0.0.0.0 + restart.
• Q: Where is the data, and does deleting the container lose it? A: all in the volume (webui.db + uploads/ + vector_db/). With -v open-webui:/app/backend/data, deleting the container keeps data; without the volume it is lost.
• Q: What role is the first registered account? A: the first user is admin automatically; later registrations are regular users.
• Q: Can I connect cloud models? A: yes, connection settings support OpenAI-compatible remote addresses (not tested; UI capability).
• Q: Where do I report issues? A: install/uninstall issues go through this entry's feedback; project issues go to the author repo.

• Version: main (manifest tracks main; image measured 2026-09-01).
• Environment: Docker 29.1.3 (WSL2 Ubuntu measured); RAM ≥4GB, 8GB+ recommended; disk ≥10GB.
• Network: ghcr.nju.edu.cn measured working (twice); pip form Python 3.11~3.12.
• Write surface: Docker volume open-webui (/app/backend/data); pip form ~/.open-webui/.
• Port: 8080 in container, host mapping your choice (example 3000); ollama interop 11434.

• Sources: official project docs (English README/docs) + local measurements (2026-08-30/09-01)
• Entry signature: open-webui/open-webui (Open WebUI License: BSD-3 base + brand terms: ≤50 users/30 days rebranding OK, above requires written/enterprise authorization)

• Measured: local repro log 2026-09-01 (Docker full chain: ghcr.nju image → healthy → /health 200 → signup admin → signin → /api/models shows ollama models → real chat inference)
• Not tested: pip normal path (Python 3.14 here refuses install, honestly marked); remote OpenAI-compatible model integration; multi-user permission details.