Getting Open WebUI and Ollama running together on one machine takes two installs and one connection setting. Ollama provides the model runtime and a local HTTP API; Open WebUI provides the chat interface, accounts, history, and model management on top of it. The project’s quick start describes Docker as “officially supported and recommended for most users,” and the documented command starts the interface on port 3000 with a persistent data volume in one line.
This guide is written for a technically curious beginner or intermediate practitioner who wants a working local chat interface and an understanding of what each piece does. It follows the documented setup rather than a personally tested configuration, and it flags the places where the documentation leaves gaps.
What you are actually assembling
Open WebUI describes itself as “a home for AI, a self-hosted AI platform that’s extensible, feature-rich, user-friendly, and built to run entirely offline.” It supports Ollama and OpenAI-compatible APIs, which makes it provider-agnostic: the interface stays the same whether the model behind it is a local file on your disk or a cloud endpoint.
The practical consequence of that split matters for troubleshooting. Open WebUI is not the model and not the inference engine. If a prompt is slow, the cause is usually the model, the hardware, or the runtime — not the web interface. If the model list is empty, the cause is almost always the connection between the two components rather than Open WebUI itself.
Ollama is the component that loads model weights and answers requests over a local API, conventionally on port 11434. Open WebUI ships with a container that listens on port 8080 internally, which the documented command maps to port 3000 on your machine.
Prerequisites: Docker, Ollama, disk, and ports
Before starting, confirm the following:
- Docker installed. The quick start states that the Docker method requires Docker to be present. Docker Desktop covers macOS and Windows; Docker Engine covers Linux.
- Ollama installed and running on the same machine, or on a host the container can reach.
- Disk space. The standard
:mainimage is 1.62 GB to download on Linux/amd64, before any model weights. The slim variants are about 196 MB — roughly 88% smaller on that platform — and are documented as offering the same chat experience with your model provider. - A free port. Port 3000 for the interface, and whatever port Ollama uses. If 3000 is taken, change the left-hand number in the port mapping.
Open WebUI’s documentation states that it works on macOS, Linux (x86_64 and ARM64, including Raspberry Pi and NVIDIA DGX Spark), and Windows. The retrieved documentation does not publish minimum RAM or CPU requirements, so treat any hardware sizing advice you find elsewhere as separate from the official setup instructions.
A note on memory sizing
Model file size is not the same as memory use. A running model needs room for its weights plus the context or KV cache and runtime overhead, and those grow with context length and concurrency. If you are choosing a model for a specific machine, plan for more than the download size and verify empirically rather than assuming a figure.
Step 1: Install and verify Ollama
Install Ollama using the instructions for your operating system from Ollama’s own documentation, then confirm the service is running and that you have at least one model available. The exact install steps differ by platform and are outside the scope of the Open WebUI documentation retrieved here, so follow the vendor’s current guidance.
Two checks are useful before you involve Open WebUI at all:
ollama list
curl http://localhost:11434/api/tagsThe first lists locally available models. The second asks the Ollama API directly for the same information. If the second command returns a JSON payload listing models, the runtime is healthy and reachable from your shell. If it fails, fix that first — Open WebUI will not be able to reach Ollama either.
If no model is present, pull one before continuing. Model names and sizes change over time, so choose from Ollama’s current library rather than from a fixed list in a guide.
Step 2: Start Open WebUI with a stable secret key
The documentation instructs you to generate a secret key and keep it. Generate one with:
openssl rand -hex 32Then run the documented container command, substituting the output of that command for your-secret-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:mainHere is what each part does, according to the quick start:
| Flag | Effect |
|---|---|
-p 3000:8080 | The UI is on port 3000 of your machine. Change the left number if 3000 is taken. |
-v open-webui:/app/backend/data | Chats, users, and settings live in this volume. It survives updates; the documentation says never to run without it. |
--add-host=host.docker.internal:host-gateway | Lets the container reach Ollama, or anything else, running on your machine. |
--restart always | The container comes back after a reboot. |
-e WEBUI_SECRET_KEY=... | Set it once and keep it. Without a fixed key, every recreated container logs everyone out. |
Confirm the container is running with docker ps. If it exits immediately, inspect the logs with docker logs open-webui — the most common causes are an occupied port or a malformed environment variable.
Step 3: Create the first account
Open http://localhost:3000 in a browser. In a default installation, the first account registered becomes the administrator account, so create it deliberately and store the credentials somewhere durable rather than using a throwaway password.
This is also the point at which the secret key decision pays off. The documentation is explicit that without a fixed WEBUI_SECRET_KEY, every recreated container logs everyone out, because session tokens are invalidated when the key changes. If you have already been logged out after an update, that is the first thing to check.
Step 4: Connect Open WebUI to Ollama
Open WebUI reaches Ollama through an API URL configured in its settings, under the connections area of the admin panel. The value depends on where Ollama runs relative to the container:
- Ollama on the same host, Open WebUI in Docker: use
http://host.docker.internal:11434. This is precisely why the documented command includes the--add-hostflag. - Ollama in another container: use the container name or a shared Docker network address instead of the host alias.
- Ollama on another machine: use that machine’s address, and make sure the runtime is configured to accept connections from outside its own loopback interface.
Open WebUI also accepts any OpenAI-compatible API alongside local Ollama models. The repository lists LMStudio, GroqCloud, Mistral, OpenRouter, and vLLM among the endpoints you can point it at, which is useful if you want a single interface for both local and hosted models.
Verifying the setup
A working installation passes all four of these checks:
docker psshows theopen-webuicontainer running.- The browser loads the interface at port 3000 and you can sign in.
- The model selector lists at least one model — the one you confirmed with
ollama list. - A short prompt returns a response, and the response streams rather than failing silently.
If the connection test in settings succeeds but no models appear, the problem is usually that Ollama has no models pulled, not that the connection is broken. If the connection test fails, move outward: test the Ollama API from your shell first, then from inside the container.
Common problems and how to diagnose them
The container will not start, or exits immediately. Check docker logs open-webui. A port conflict on 3000 is the most frequent cause; change the left side of -p to another free port.
The browser cannot reach the interface. Confirm the container is running and that you are using the host port you mapped, not 8080, unless you mapped that number explicitly.
Open WebUI cannot reach Ollama. Verify Ollama answers locally first. Then confirm the container can resolve the host: the --add-host flag exists for exactly this purpose. A runtime bound only to loopback on the host may also refuse connections that arrive from the container’s network namespace.
Everyone is logged out after an update. The secret key changed. Recreate the container with the same WEBUI_SECRET_KEY value you originally generated.
Chats and users disappeared. The data volume was omitted or a different volume name was used. The documented volume name is open-webui, mounted at /app/backend/data.
Choosing an image variant
The quick start documents several tags, and the choice affects download size and hardware support more than features:
| Tag | Documented use case |
|---|---|
:main | Standard image, recommended. Includes the app plus bundled speech-to-text and embedding models. |
:dev | Pre-release nightly build from the dev branch; fixes and features arrive here first. |
:slim, :main-slim | About 196 MB instead of 1.62 GB on Linux/amd64. Same chat experience with your model provider. |
:cuda | NVIDIA GPU support, CUDA 12.8, run with --gpus all. |
The repository README also mentions :ollama and :cuda tagged images as available for container deployments. The retrieved documentation does not detail what the :ollama tag bundles, so verify against current docs before relying on it.
Updating, backups, and day-two operations
Because state lives in the named volume, updating is a matter of pulling a newer image and recreating the container with the same volume and the same secret key. Reusing both is what makes the update invisible to users.
Back up the volume before major upgrades. The volume holds chats, users, and settings — the things that are not reproducible from configuration. The container itself is disposable; the volume is not.
Limitations and tradeoffs to weigh
Docker is recommended, not mandatory. The project documents installation via pip, uv, Docker, and Kubernetes, with Kubernetes positioned for enterprise deployments requiring scaling and orchestration, and Python positioned for low-resource environments or manual setups. If Docker is unavailable on your machine, a Python install is a documented alternative rather than an unsupported workaround.
The claim that Open WebUI is “built to run entirely offline” describes the application and local models. Connecting it to a cloud OpenAI-compatible endpoint obviously involves network traffic to that provider, so decide per deployment what “local” needs to mean for your data.
Licensing deserves a direct check rather than an assumption. The GitHub repository metadata lists the license as “Other,” which is not the same as a standard permissive license. Read the actual license text before commercial or redistributed deployment. Similarly, open weights, open source, and commercial-use permission are three different things, and the model you run carries its own license separate from the interface.
Finally, note the project’s scale and pace: the repository reported roughly 154,000 stars and 22,500 forks at the time this was written, with an active issue tracker. That activity is a strength for fixes, but it also means the :dev tag moves quickly and documentation can lag behind the nightly branch.
Where to go next
Once the connection is verified, the useful next steps are operational rather than technical: pick a model that fits your hardware after measuring actual memory use, decide which chats should stay local, and write down the secret key and volume name somewhere you will find them before the next update. If something breaks, reproduce it with the two commands from Step 1 — ollama list and a direct request to the Ollama API — because that separates a runtime problem from an interface problem in seconds. Readers working through this setup are welcome to share their environment, the exact command they ran, and any error output in the community, since the failure modes above are far easier to diagnose with those three details.
FAQ
Do I have to use Docker to run Open WebUI?
No. The project documents installation via pip, uv, Docker, and Kubernetes. Docker is described as officially supported and recommended for most users, Kubernetes is positioned for enterprise deployments needing scaling and orchestration, and Python is positioned for low-resource environments or manual setups.
Why does everyone get logged out after I update the container?
Because WEBUI_SECRET_KEY changed. The documentation states that without a fixed key, every recreated container logs everyone out. Recreate the container with the same key value you generated originally.
Can Open WebUI use cloud models as well as local ones?
Yes. It supports Ollama and OpenAI-compatible APIs, and the repository lists LMStudio, GroqCloud, Mistral, OpenRouter, and vLLM among endpoints you can point it at. Note that cloud endpoints mean network traffic leaves your machine, unlike purely local inference.
The connection test succeeds but no models are listed. What is wrong?
Most often there are no models available in Ollama. Run ollama list on the host and pull a model if the list is empty. If models exist locally and still do not appear, re-check the API URL the container is using.