Joshua Opolko

Open WebUI: Install and Configure the Best Interface for Ollama and Local LLMs

Key takeaways - Open WebUI v0.9.6 installs in a single Docker command and is ready in under five minutes - Docker is the recommended install method. A pip path is available for Python 3.11 or 3.12 (Python 3.13 is not yet supported) - Ollama is optional. Open WebUI connects to any OpenAI-compatible API, including OpenAI, OpenRouter, LiteLLM, and local Ollama - When Ollama runs on the same machine as the Docker container, use host.docker.internal on Mac/Windows or --network=host on Linux to avoid a "connection refused" error - The first account you create becomes the admin. All later sign-ups create regular user accounts. Disable registration after setup to lock down a personal install - Set WEBUI_SECRET_KEY in production so all user sessions survive container restarts and updates - RAG (document chat) is built in. Upload PDFs, Word docs, and web pages to a Knowledge collection, then reference it in any chat with the # shortcut - Open WebUI ships as a PWA, so you can install it to your desktop or phone home screen and it opens like a native app

How do I install Open WebUI?

Run a single Docker command and Open WebUI is available at http://localhost:3000 within seconds. No existing Ollama installation is required for the standalone image.

Standalone (no bundled Ollama):

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

Bundled with Ollama (CPU only):

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

Bundled with Ollama (NVIDIA GPU):

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

After the container starts, open http://localhost:3000 in your browser. The first screen asks you to create an account. That account becomes the site administrator.

If you prefer pip over Docker, make sure you are on Python 3.11 or 3.12:

pip install open-webui
open-webui serve

To update a Docker install, pull the new image and recreate the container. Your data is in the named volume open-webui and is preserved across updates:

docker pull ghcr.io/open-webui/open-webui:main
docker stop open-webui && docker rm open-webui
# re-run your original docker run command

How do I connect Open WebUI to Ollama?

If you used the bundled :ollama image, the connection is already configured. If Ollama is running separately on your host machine, set the OLLAMA_BASE_URL environment variable so the container knows where to find it. The reason: localhost inside a Docker container resolves to the container itself, not your host.

Mac or Windows:

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

Linux (use host networking):

docker run -d \
  --network=host \
  -e OLLAMA_BASE_URL=http://127.0.0.1:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

With host networking the container shares the host's network stack, so Open WebUI binds to port 8080 directly. Access it at http://localhost:8080 instead of 3000.

To connect to a remote Ollama instance, use its IP address: -e OLLAMA_BASE_URL=http://192.168.1.50:11434.

You can also add or change Ollama endpoints after setup: go to Admin Panel, Settings, then Connections. No restart required.

How do I use Open WebUI without Ollama?

Open WebUI works with any OpenAI-compatible API. Point it at OpenAI, OpenRouter, a LiteLLM proxy, or any other backend that implements the /chat/completions endpoint. Ollama is not required.

Go to Admin Panel, Settings, then Connections and add a new OpenAI-type connection. For the real OpenAI API:

Or pass these at container startup:

docker run -d \
  -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.openai.com/v1 \
  -e OPENAI_API_KEY=sk-... \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

For a local LiteLLM proxy (which lets you front Anthropic, Google, and others behind an OpenAI-compatible layer):

-e OPENAI_API_BASE_URL=http://host.docker.internal:4000
-e OPENAI_API_KEY=anything

Open WebUI supports multiple connections simultaneously. You can have local Ollama models and cloud GPT-4o in the same model picker and switch between them per conversation.

What can I do with Open WebUI?

Open WebUI is a full-featured self-hosted AI platform, not just a chat wrapper.

Chat and multi-model comparisons. Talk to any model, compare responses from two models side by side in a split view, and switch models mid-conversation without losing context.

Retrieval Augmented Generation. Upload PDFs, Word documents, spreadsheets, and text files. Open WebUI indexes them into a vector database and retrieves relevant chunks to pass to the model when you ask questions.

Web search integration. Connect to SearXNG, Brave Search, DuckDuckGo, Tavily, or 15+ other search providers. A globe icon in the chat bar lets users toggle web search per conversation.

Custom model presets and agents. Bundle a system prompt, a set of tools, and a knowledge base into a reusable "Model" in the Workspace. Share it with other users on your instance.

Team channels. Channels are shared spaces where multiple users can chat and tag specific models with @model-name to pull them into the conversation, with threading and access controls.

Open Terminal. The integrated code execution environment lets the model write code, run it, read the output, fix errors, and iterate, all inside the chat window.

MCP and tools. Connect Model Context Protocol servers for file system, calendar, browser, and other integrations.

Image generation. Wire up AUTOMATIC1111, ComfyUI, or DALL-E for image generation inside the same interface.

Voice. Dictate messages with speech-to-text and hear responses read back with text-to-speech.

PWA install. In Chrome, Edge, or Safari, click "Add to Home Screen" or the install icon in the address bar. It opens in a frameless window like a native application, on desktop or mobile.

How do I set up RAG in Open WebUI?

RAG works out of the box with no extra configuration for basic use. Upload a file directly in a chat or build a persistent Knowledge collection in the Workspace.

Quick file upload in chat:

  1. Open a chat.
  2. Click the paperclip icon and upload a file. Supported formats include PDF, DOCX, TXT, and CSV.
  3. Ask questions. Open WebUI extracts the relevant passages and includes them in the model's context window.

Persistent Knowledge collections (recommended for reuse):

  1. Go to Workspace, then Knowledge.
  2. Click "+ New Knowledge" and give it a name and description.
  3. Upload files or add URLs. Open WebUI fetches and indexes page content from URLs automatically.
  4. In any chat, type # followed by the knowledge base name to attach it to that conversation.

The default vector store is ChromaDB, which runs inside the Open WebUI container with no extra setup. For larger document libraries, you can swap to Qdrant, PGVector, Milvus, Elasticsearch, or Pinecone via environment variables.

Enable hybrid search for better accuracy on technical or keyword-heavy documents:

-e ENABLE_RAG_HYBRID_SEARCH=true

Hybrid search combines BM25 keyword matching with vector similarity, then re-ranks the merged results. On code, legal text, and product documentation it typically retrieves better passages than vector search alone.

How do I manage users and secure my instance?

The first account on a fresh install automatically becomes the administrator. Subsequent sign-ups create regular user accounts.

For a personal, single-user install, disable sign-up and the login screen entirely:

-e WEBUI_AUTH=False

Do not use this on a machine reachable from the public internet.

For a shared team install, set a stable WEBUI_SECRET_KEY. Without it, Open WebUI generates a random JWT signing key each time the container starts, which logs out all users on every restart or update.

# Generate a key once and store it somewhere safe
openssl rand -base64 32

# Add to your Docker run command or Compose file
-e WEBUI_SECRET_KEY=your-generated-key-here

From the Admin Panel you can view and manage all registered users, approve or reject pending registrations, and share model presets and knowledge bases with specific users or roles. For larger teams, Open WebUI supports LDAP, OIDC/SSO, and SCIM 2.0 user provisioning.

Troubleshooting

  1. Open WebUI can't reach Ollama: "connection refused" or "connection error" What you see: A red "Connection error" banner at the top of the page, or the model picker shows no Ollama models. What it is: localhost inside the Docker container resolves to the container itself, not your host machine where Ollama is listening on port 11434. The fix: On Linux, add --network=host and set OLLAMA_BASE_URL=http://127.0.0.1:11434. On Mac or Windows, add --add-host=host.docker.internal:host-gateway and set OLLAMA_BASE_URL=http://host.docker.internal:11434.

  2. Model list is empty even though Ollama has models installed What you see: The model picker shows no local models, and ollama list on the host shows models correctly. What it is: Ollama may be bound to 127.0.0.1 only and not accepting connections from outside the host's loopback interface. The fix: Start Ollama with OLLAMA_HOST=0.0.0.0 ollama serve, or add that variable to your Ollama system service configuration and restart it.

  3. Chat responses display raw markdown symbols What you see: Responses appear as unformatted plain text with visible asterisks and hash symbols. What it is: If you are proxying Open WebUI behind nginx, the default response buffering breaks streaming output. The fix: Add these two lines to your nginx location block: proxy_buffering off; and proxy_cache off;.

  4. All users get logged out on every container restart What you see: Users are forced to log in again every time the container restarts or is updated. What it is: Open WebUI auto-generates a new JWT signing key at startup when WEBUI_SECRET_KEY is not set. Each new key invalidates all existing sessions. The fix: Generate a key once with openssl rand -base64 32 and add -e WEBUI_SECRET_KEY=your-key to your Docker command or Compose file.

  5. RAG returns empty or irrelevant results What you see: The model says it has no information about the uploaded document, or answers questions about wrong content. What it is: The file may have failed to parse (common with scanned PDFs), or the chunk and embedding settings are not suited to your documents. The fix: Go to Admin Panel, Settings, then Documents and check for parsing errors. Enable hybrid search with -e ENABLE_RAG_HYBRID_SEARCH=true. For scanned PDFs, try switching the content extraction method to one with OCR support.

Frequently asked questions

Is Open WebUI free? Yes. Open WebUI is released under the MIT license and is free to self-host. Your costs are the server you run it on and any API charges from external providers you connect to. A managed cloud-hosted version is available at openwebui.com if you prefer not to manage your own server.

Does Open WebUI support multiple users? Yes. The first account created is the admin. All subsequent registrations are regular user accounts. Admins can approve or reject registrations, assign roles, and share resources. For enterprise deployments, LDAP, OIDC/SSO, and SCIM 2.0 provisioning let you manage users through an existing identity provider.

What is the difference between Open WebUI and Ollama? Ollama is the runtime that downloads and runs local language models on your machine. Open WebUI is the browser-based front end you use to chat with those models. Think of Ollama as the engine and Open WebUI as the dashboard. Open WebUI also connects to OpenAI, LiteLLM, OpenRouter, and any other OpenAI-compatible API, so it is not limited to Ollama.

Can I run Open WebUI on a Raspberry Pi or low-power hardware? Open WebUI itself is lightweight and runs fine on a Pi. The bottleneck is the LLM backend. On a Pi you would connect to a small Ollama model (1-3 billion parameters), which is slow but functional for personal use. For a faster experience on CPU-only hardware, a modern x86 machine with 16 GB of RAM handles 7B-parameter models at a usable speed.

Does Open WebUI work on mobile? Yes. The interface is fully responsive. You can also install it as a PWA from Chrome on Android or Safari on iOS by tapping "Add to Home Screen."

Resources

Last updated: June 27, 2026.