Open WebUI + Ollama Setup Guide (2026): Docker, Python, Connect Models and Fix Errors

Ollama is great at running models, but its own chat window is basic. Open WebUI gives you a full ChatGPT-style interface on top: chat history, file uploads, web search, voice, image generation and multiple users.

It is free, runs on your own PC, and talks to Ollama on localhost:11434 with almost no setup.

This guide covers both install routes (Docker and Python), connecting Ollama, the features worth switching on, and fixes for the connection errors almost everyone hits once.

What Is Open WebUI?

Open WebUI is a self-hosted web app for chatting with AI models. It works with Ollama, OpenAI, Anthropic and any OpenAI-compatible server from one interface.

Think of it as your own private ChatGPT. Everything, including chats and uploaded files, stays in a data folder on your machine.

• Chat: history, folders, model switching mid-chat, and side-by-side model comparison.
• Your documents: upload files or build knowledge bases and ask questions about them.
• Tools: web search, Python tools, MCP servers and a code interpreter.
• Multi-user: roles, groups and permissions, so a family or small team can share one server.

Before You Start

• Ollama installed and running with at least one model pulled. My Ollama install guide covers Windows, Mac and Linux.
• Docker Desktop (Windows/Mac) or Docker Engine (Linux), if you use the Docker route.
• Or Python 3.11/3.12 for the pip route. Python 3.13 is not supported yet.
• About 2-4 GB of disk for the app, plus space for your models.

Test Ollama first with ollama run llama3.2 or any model you have. If that does not work, Open WebUI will not either.

Install With Docker (Recommended)

1. Create a secret key so logins survive container updates:

   openssl rand -hex 32

   Copy the output.

2. Run the container (one line, paste your key):

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

3. Open http://localhost:3000 in your browser. The first start can take a minute.
4. Click Create Admin Account. This first account is the admin.
5. Pick a model from the top-left menu and say hello.

What the flags do:

• -p 3000:8080: the app listens on 8080 inside the container, you open 3000 on your PC. Change 3000 if it is taken.
• --add-host=host.docker.internal:host-gateway: lets the container reach Ollama on your PC.
• -v open-webui:/app/backend/data: keeps your chats and users in a Docker volume. Never skip it.

Other image tags

Tip: keep Ollama as its own app (the :main route). You can then update either one without touching the other, and other tools like VS Code agents can share the same Ollama.

Install With Python or uv (No Docker)

1. Create a virtual environment with Python 3.11 or 3.12:

   python -m venv owui
   source owui/bin/activate     # Linux/Mac
   owui\Scripts\activate        # Windows

2. Install:

   pip install open-webui

3. Start it:

   open-webui serve

4. Open http://localhost:8080 and create the admin account.

Prefer uv? One command does it, with your data kept in ~/.open-webui:

DATA_DIR=~/.open-webui uvx --python 3.12 open-webui@latest serve

Note: without WEBUI_SECRET_KEY, the Python install saves a key to .webui_secret_key in the folder you started from. Always start it from the same folder, or set DATA_DIR and the key yourself.

Connect Ollama and Pick a Model

In most setups there is nothing to do: Open WebUI checks the default Ollama address on start.

1. Check the connection in Admin Panel > Settings > Connections. Fix or add the Ollama URL there and save.
2. Pull models from the UI if you like: Admin Panel > Settings > Models lets you download Ollama models by name.
3. Choose a model that fits your GPU. My best Ollama models by VRAM list is a good start.
4. Set a bigger context for document chat in the model’s Advanced Params (num_ctx), or Ollama will cut long files.

Features Worth Turning On

Chat with your documents

Drag a PDF into a chat, or build a reusable Knowledge base in Workspace. You can choose vector search (RAG) or full-document injection, and hybrid search (BM25 + vector) is built in.

Web search

Enable it in Admin Panel > Settings > Web Search and pick a search provider. Answers then cite their sources.

Tools and MCP

Open WebUI can call Python tools, OpenAPI servers and MCP servers over Streamable HTTP. For server ideas, see my best MCP servers list. Only add tools you trust; they run with the server’s permissions.

Image generation with ComfyUI

Point Open WebUI at your ComfyUI server in Admin Panel > Settings > Images to create pictures from chat. GPT-Image and Gemini are also supported if you add API keys.

Voice

Speech-to-text, text-to-speech and hands-free voice calls are built in. Turn them on under Audio settings.

Custom models (agents)

Workspace > Models lets you wrap any model with a system prompt, tools, knowledge and settings, for example a “Code Reviewer” or “Study Buddy”.

Update, Back Up and Remove

• Update (Docker): docker pull ghcr.io/open-webui/open-webui:main, then docker rm -f open-webui and run the same docker run command with the same secret key. Your data stays in the volume.
• Update (Python): pip install -U open-webui, then open-webui serve.
• Back up: copy the open-webui Docker volume or your DATA_DIR folder. That holds chats, users and settings.
• Remove: docker rm -f open-webui and docker volume rm open-webui (this deletes all chats).

Warning: docker volume rm open-webui permanently deletes every chat and user. Back up the volume first if there is anything you want to keep.

Open WebUI vs LM Studio vs Ollama App

For the engines underneath, see my Ollama vs LM Studio vs llama.cpp comparison.

Troubleshooting

No models listed or “Cannot connect to host”

Ollama is only listening on 127.0.0.1, which the container cannot reach. Set OLLAMA_HOST=0.0.0.0 (in Windows environment variables, your shell profile or the systemd service), restart Ollama, then refresh Open WebUI.

Docker on Linux cannot find Ollama

Make sure the --add-host=host.docker.internal:host-gateway flag is in your run command. Or use --network=host with OLLAMA_BASE_URL=http://127.0.0.1:11434; the UI is then on port 8080, not 3000.

Model menu spins forever or /api/models returns 500

One saved connection URL is dead and each one waits 10 seconds. Remove bad URLs in Admin > Connections, and set AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=3 to fail faster.

Changing OLLAMA_BASE_URL does nothing

Settings saved in the database override environment variables. Edit the URL in Admin > Connections, or start once with RESET_CONFIG_ON_START=true.

“Open WebUI backend required”

Your port mapping points at the wrong port. The container port is always 8080 (for example -p 3001:8080). Test with curl http://localhost:3001/api/config; JSON means the backend is up.

“Model not found” that comes and goes

A DNS resolver quirk on some Windows and Docker setups. Leave AIOHTTP_CLIENT_ASYNC_DNS_RESOLVER off (the default).

Replies are slow

Usually the model is too big and spilling into system RAM. Check with my GPU VRAM usage guide and pick a smaller quant.

My Take

If you already use Ollama, Open WebUI is the single best upgrade you can make. Ten minutes of setup gets you document chat, web search and a proper chat history, and you can open it from your phone on the same Wi-Fi.

I would go with Docker and the :main image, keep Ollama as a separate app, and set a fixed secret key from day one so updates never log everyone out.

FAQ

Is Open WebUI free?

Yes. It is free to self-host. It uses its own Open WebUI License, so check that page if you plan to rebrand it for a business.

Does Open WebUI need Docker?

No. You can install it with pip install open-webui on Python 3.11 or 3.12, or run it with uv. Docker is just the easiest to update.

What port does Open WebUI use?

The app listens on 8080. The standard Docker command maps it to 3000 on your PC, so you open http://localhost:3000.

Why can’t Open WebUI see my Ollama models?

Usually Ollama only listens on 127.0.0.1 or the URL is wrong. Set OLLAMA_HOST=0.0.0.0, restart Ollama and check the URL in Admin > Connections.

Can I use Open WebUI with ChatGPT or Claude APIs too?

Yes. Add OpenAI, Anthropic or any OpenAI-compatible endpoint in Admin > Connections and use them next to your local models.

Is my data private with Open WebUI?

Chats and files stay in your local data folder or Docker volume. Only requests you send to cloud APIs leave your machine.

Can I open Open WebUI on my phone?

Yes. Open http://<your-PC-IP>:3000 from a phone on the same network, and allow the port in your PC’s firewall.

Sources

• Open WebUI docs: Quick Start
• Open WebUI docs: Connection errors
• Open WebUI docs: Features
• GitHub: open-webui/open-webui