What you will run into

You are already chatting with ollama run qwen2.5>>> in the terminal, but the interface is plain text — you cannot upload a document and ask questions over it, switch models with the mouse, or browse chat history. So you find open-webui and run pip install open-webui>>>, only to get Could not find a version that satisfies the requirement open-webui>>>. Docker users have it worse: docker pull ghcr.io/open-webui/open-webui>>> spins forever and times out. This guide is the verified path: Docker form via the mainland-China ghcr mirror (ghcr.nju.edu.cn, verified working), or pip form after downgrading Python to 3.11/3.12. When done you get: a browser chat UI (http://localhost:3000 or your chosen port), automatic connection to Ollama, and an optional local knowledge base. When to use it:

• You want a web chat UI for your local LLM (more visual than CLI: chat history, model switching);
• You want a local RAG knowledge base: feed documents, get answers grounded in your material (full chain verified 2026-08-30 in combo combo-local-llm-finetune);
• You want a LAN chat entry point for your team/family (note: personal use under 50 users is fine, see FAQ license entry).

When not to use it: if terminal chat is enough, `ollama run>>> already does it; for enterprise multi-tenant/audit needs, open-webui is not purpose-built for that.

Path: Quick fix (one command) -> Step by step (skimmable) -> How to confirm it works (success criteria) -> Daily usage (long-term operations) -> Uninstall. In a hurry? Jump to Quick fix.

Why this happens

open-webui is the most widely used web UI in the Ollama ecosystem (150k+ GitHub stars). It is a Python application (FastAPI + uvicorn + SQLite) shipped in two forms:

• Docker image form: the image bundles all dependencies and a data directory (/app/backend/data); one `docker run>>> brings it up. This is the recommended path and the easiest on mainland networks — the image can be pulled through a China ghcr mirror.
• pip form: pip install open-webui>>> runs directly on your system Python. Note: every historical version of open-webui requires Python 3.11~3.12 (Requires-Python <3.13.0a1,>=3.11>>>, verified 2026-09-01). Ubuntu 24.04 ships Python 3.12 by default; but if you installed a newer Python (3.13/3.14) manually, pip refuses to install — this is the most common "cannot install" cause.

Two key mechanisms:

• OLLAMA_BASE_URL>>> (or "Connection settings" in the UI): open-webui does not run models itself; it calls the Ollama API at this address (default http://localhost:11434). In Docker form, use host.docker.internal>>> or the host gateway address to reach host Ollama (verified 172.17.0.1).
• Data lives in webui.db>>> (SQLite) + uploads/>>> + `vector_db/>>>: accounts, conversations, uploaded documents, and the RAG vector store. In Docker form, always mount a volume so removing the container keeps your data.

Where it writes: Docker volume (data directory); pip form = Python package (site-packages) + a data directory (default ~/.open-webui/).

Step by step

Step 1: Install the Docker form

Explanation: the image bundles Python and all dependencies, bypassing the pip form's Python version cap. The key for mainland networks is the image prefix: official is ghcr.io>>> (direct connection verified timeout), switch to ghcr.nju.edu.cn>>> (Nanjing University mirror; pull verified 2026-08-30 in the combo, cached-image start verified 2026-09-01). Mount data to volume open-webui>>> so removing the container keeps accounts and conversations. --add-host=host.docker.internal:host-gateway>>> lets the container reach the host via `host.docker.internal>>> (used for Ollama). `agent 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

>>

预期输出: a container ID (e.g. 5e7e82f26c89..., verified 2026-09-01)

Confirm it is installed:

• docker ps | grep open-webui>>> shows Up>>>;
• first start initializes the database; health check goes from starting>>> to healthy>>> in ~1-2 minutes (a brief `unhealthy>>> in between is normal; verified turning healthy on the 18th check).

If stuck:

• Image pull stalls (ghcr.io timeout) -> switch the prefix to `ghcr.nju.edu.cn>>> (verified 2026-08-30/09-01); or pull once through a proxy to cache, then start with the China prefix.
• Port 3000 taken -> change the host mapping to `-p 3001:8080>>> and open http://localhost:3001.
• Docker missing -> install Docker first (`curl -fsSL https://get.docker.com | sh>>> or your distro package manager), then come back.

Step 2: First open + register admin

Explanation: the first registered user becomes admin automatically (verified: signup API returns role=admin). Later registrations are regular users. For LAN sharing you can turn off the signup toggle under Settings -> Interface. `bash

open in a browser

http://localhost:3000

or verify the signup endpoint via CLI (first user is admin)

curl -s -X POST http://localhost:3000/api/v1/auths/signup \ -H "Content-Type: application/json" \ -d '{"name":"tester","email":"you@example.com","password":"your-password","role":"admin"}'

>>

预期输出: browser shows the signup/login page; curl returns `{"id":"...","role":"admin","token":"eyJ..."}>>> (verified 2026-09-01)

If stuck:

• Signup returns 405 Method Not Allowed -> confirm POST to /api/v1/auths/signup; sign-in uses /api/v1/auths/signin (verified 2026-09-01: the two endpoints differ, using signup for login gives 405).
• Signup page spins / will not open -> wait until the health check is healthy (`docker inspect open-webui --format '{{.State.Health.Status}}'>>>) and refresh.
• LAN users register as regular users -> an admin turns off the signup toggle under Settings -> Interface.

Step 3: Connect to Ollama (automatic + manual)

Explanation: open-webui does not run models itself. Without an explicit OLLAMA_BASE_URL>>> at container start, it defaults to http://host.docker.internal:11434>>> (reaching the host from inside the container). Add `-e OLLAMA_BASE_URL=http://host.docker.internal:11434>>> to set it explicitly. It can also be changed under Settings -> Connection in the UI. `bash

verify host Ollama is running (outside the container)

curl -s http://localhost:11434/api/tags

verify the container can reach host Ollama (inside the container)

docker exec open-webui curl -s http://172.17.0.1:11434/api/tags

>>

预期输出: each returns a `{"models":[...]}>>> list containing your pulled models (qwen2.5-0.5b visible, verified)

If stuck:

• curl inside the container fails/times out -> check where Ollama listens: the snap build in WSL2 listens on 127.0.0.1 by default, unreachable from the container; restart Ollama with `OLLAMA_HOST=0.0.0.0>>> or connect via the host IP directly (172.17.0.1 verified reachable).
• Still failing after changing the address in Connection settings -> save, then restart the container (`docker restart open-webui>>>) and check the model list again.

Step 4: pip form (when you do not want Docker)

Explanation: the pip form installs the Python application into your system environment. Hard prerequisite: Python 3.11 or 3.12. Every open-webui version requires Requires-Python <3.13.0a1,>=3.11>>> — Python 3.13/3.14 cannot install at all (verified 2026-09-01: 3.14.4 + pip 25.1.1 gives Could not find a version that satisfies the requirement>>>). Ubuntu 24.04 ships 3.12 so it works directly; if you installed a newer Python, use pyenv to install 3.12 and create a virtualenv: `agent

first confirm the Python version (must be 3.11 or 3.12)

python3 --version

Ubuntu 24.04 default 3.12 can install directly; otherwise install pyenv + Python 3.12 first

pip install open-webui --index-url https://pypi.tuna.tsinghua.edu.cn/simple open-webui serve

>>

预期输出: `open-webui serve>>> starts uvicorn (default port 8080); open http://localhost:8080 in a browser

If stuck:

• Could not find a version that satisfies the requirement open-webui>>> -> not a network problem; the Python version is wrong. If python3 --version>>> shows 3.13/3.14, install Python 3.12 and use it in a virtualenv (verified root cause, 2026-09-01).
• Heavy dependencies (PyTorch, hundreds of MB) -> use the Tsinghua PyPI mirror (already in the command above).

How to confirm it works

`bash

1. health check (Docker form)

curl -s http://localhost:3000/health

预期输出: {"status":true} (verified http 200 on 2026-09-01)

2. sign in for a token

curl -s -X POST http://localhost:3000/api/v1/auths/signin \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"your-password"}'

预期输出: JSON containing "token":"eyJ..."

3. open-webui lists the Ollama models (use the token from above)

curl -s http://localhost:3000/api/models -H "Authorization: Bearer <token>"

预期输出: {"data":[{"id":"qwen2.5-0.5b:latest","owned_by":"ollama",...}]}

4. chat for real (open-webui -> ollama full chain)

curl -s http://localhost:3000/api/chat/completions \ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-0.5b:latest","messages":[{"role":"user","content":"Say OK"}],"stream":false}'

预期输出: choices[0].message.content is the model reply (verified "OK, thank you.", 6 output tokens)

>>

In the browser: after signing in you can see the model list, create a conversation and get a reply — the full chain works.

Other environments (common variants)

• Windows (Docker Desktop + WSL2): the environment verified in this guide. The docker run>>> command works as-is; open http://localhost:3000>>> in the browser; with Ollama installed on the host inside WSL2, the container reaches it via 172.17.0.1>>> or host.docker.internal>>> (172.17.0.1 verified reachable on 2026-09-01).
• macOS: Docker Desktop resolves host.docker.internal natively; same commands. On Apple Silicon there is no NVIDIA GPU; inference goes through Ollama's Metal acceleration (not tested, inferred).
• Linux bare metal: the container reaches the host via --add-host=host.docker.internal:host-gateway>>> (already in the command); with systemd-managed Docker, containers started with --restart always>>> come back up automatically when Docker starts.
• pip form: in a Python 3.11/3.12 environment run pip install open-webui>>> + open-webui serve>>>, default port 8080; Python 3.14 verified cannot install (see FAQ Q1).
• LAN access: other devices on the same network use `http://<host-ip>:3000>>>; the admin account registered first works from any device (data lives in the volume).

Dependency warnings

• pip form Python version: every version requires 3.11~3.12 (`Requires-Python <3.13.0a1,>=3.11>>>); 3.13/3.14 verified cannot install - the most common installation blocker.
• Docker image size: first pull ~1.8GB (combo prior measured 7.16GB including layer transfer); keep >=10GB free disk.
• Port: fixed 8080 inside the container; change the host mapping with `-p>>> if the mapped port (example 3000) is taken.
• Ollama dependency: open-webui does not run models; an Ollama service (11434) must exist first; the Docker form needs --add-host>>> or a correct OLLAMA_BASE_URL>>> (verified 2026-09-01).
• License branding clause: Open WebUI License section 4 - rebranding is limited to <=50 end users per rolling 30 days; above that, written/enterprise permission is required (checked against the original text on 2026-09-01).
• Memory: the container itself needs >=1GB; model inference is extra (model size + context).

Daily usage

Web chat and model switching

After signing in, pick a model from the dropdown at the top (it lists all Ollama models), and start a new conversation on the right. Switch models any time; history is stored in webui.db. `bash

check the current version (report this first when troubleshooting)

curl -s http://localhost:3000/api/version

预期输出: {"version":"0.11.1","deployment_id":""} (verified 2026-09-01; GitHub latest is v0.11.3)

>>

OpenAI-compatible API via CLI

open-webui exposes an OpenAI-compatible API: point base_url at `http://localhost:3000/api>>> and use the login token as the key. Scripts/agents/IDE plugins can all connect. `bash

unlike curl to Ollama directly, the open-webui endpoint needs a Bearer token

curl -s http://localhost:3000/api/chat/completions \ -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-0.5b:latest","messages":[{"role":"user","content":"hello"}],"stream":false}'

>>

预期输出: chat.completion JSON in the same format as Ollama direct (verified 2026-09-01)

Local knowledge base (RAG)

Workspace -> create a knowledge base -> upload documents, then @ the knowledge base in a reply. The embedding model is pulled from Ollama by default (nomic-embed-text); the first pull on mainland networks can be slow — run `ollama pull nomic-embed-text>>> in the terminal first (full chain verified 2026-08-30 in the combo).

Forgot the admin password

Reset with the in-container CLI (reproduced by the problem lane on 2026-08-30): `bash docker exec -it open-webui python -c "from open_webui.utils.auth import update_password_by_email; update_password_by_email('you@example.com','new-password')"

>>

预期输出: no output (exit 0); sign in with the new password. See the problem entry open-webui-reset-password.

Uninstall

`bash

stop the container

docker stop open-webui

remove the container (data stays in the volume)

docker rm open-webui

delete the data for good (conversations, accounts, knowledge bases all go - think first)

docker volume rm open-webui

>>

预期输出: the first two produce no output (exit 0); volume removal prints the volume name

pip form: `pip uninstall open-webui>>>, then delete the data directory (default ~/.open-webui/) manually.

FAQ

• 问：pip install open-webui gives `Could not find a version>>> — is it a network problem?

No. Every version of open-webui requires Python 3.11~3.12 (Requires-Python <3.13.0a1,>=3.11>>>); Python 3.13/3.14 cannot install (verified 3.14.4 on 2026-09-01). Run python3 --version>>>; if it is not 3.11/3.12, install pyenv + Python 3.12 and create a virtualenv first.

• 问：The ghcr.io image pull stalls — what now?

Switch to a China ghcr mirror prefix: `ghcr.nju.edu.cn/open-webui/open-webui:main>>> (verified twice: 2026-08-30 and 2026-09-01). Other options such as ghcr.dockerproxy.com exist but are not verified; keep as fallback.

• 问：The container is up but the browser cannot open it?

Check the mapped port: docker ps>>> PORTS column (0.0.0.0:3000->8080/tcp means host port 3000 is in use); first start needs 1-2 minutes of initialization — run docker inspect open-webui --format '{{.State.Health.Status}}'>>> until it says `healthy>>>.

• 问：The UI says it cannot connect to Ollama?

First confirm host Ollama is running (curl -s http://localhost:11434/api/tags>>>); then check in-container reachability (docker exec open-webui curl -s http://172.17.0.1:11434/api/tags>>>); finally set the Ollama Base URL under Settings -> Connection to a reachable address.

• 问：Can I rebrand Open WebUI (rename/logo) in my deployment?

The license has a dedicated clause (Open WebUI License, section 4): deployments with no more than 50 end users within any rolling 30-day period may rebrand; above 50 users you need written permission or an enterprise license from the copyright holder, otherwise it is a material breach. Personal/small-team internal use is fine; check LICENSE before commercial white-label deployment (verified against the original text on 2026-09-01).

• 问：How do I follow versions?

Docker form: :main>>> tracks the latest (container measured 0.11.1; GitHub latest is v0.11.3, released 2026-08-31); pin a specific tag (e.g. :v0.11.3>>>) for a fixed version. pip form: pip install -U open-webui>>>. Back up the volume before upgrading (docker run --rm -v open-webui:/data -v $PWD:/backup alpine tar czf /backup/open-webui-backup.tgz -C /data .>>>).

Verification evidence

• Verified 2026-09-01 (environment: WSL2 Ubuntu + Docker Desktop; evidence local repro log 2026-09-01):
• Container from ghcr.nju.edu.cn/open-webui/open-webui:main -> healthy (~1-2 min) -> /health 200 `{"status":true}>>>;
• signup first user role=admin -> signin for token -> /api/models lists the Ollama model qwen2.5-0.5b;
• /api/chat/completions real inference: replied "OK, thank you." (6 output tokens);
• version: in-container /api/version = 0.11.1; GitHub latest v0.11.3 (released 2026-08-31, no release assets = Docker/pip form);
• pip form reproduced failure: Python 3.14.4 + pip 25.1.1 -> `Could not find a version that satisfies the requirement open-webui>>> (every version Requires-Python 3.11~3.12).
• Combo prior: combo-local-llm-finetune (2026-08-30) full chain including RAG verified.