A local app can connect to an online model. Check the selected model, document storage, and connected tools before using sensitive information.
Quick answer: Install and verify Ollama first, then install Open WebUI as the browser interface. The usual beginner path is Docker: run Open WebUI in a container, persist its data in a volume, open it in your browser, create the first admin user, and confirm it can reach Ollama. The most common failure is not the model. It is the connection between a Docker container and Ollama running on the host machine.
Best for: users who already have Ollama working and want a ChatGPT-like browser interface for local models, file uploads, and a reusable workspace. Not for: users who have not yet installed Ollama, users who do not want Docker or local-server troubleshooting, or users who need a formal security-hardened deployment guide.
Privacy warning: Open WebUI can be local and private, but only if the connected model provider, embedding provider, files, storage, and network exposure are also local/private. A self-hosted Open WebUI connected to a cloud API is not a fully local AI workflow.
Before you start
Open WebUI is not the model runtime. It is the interface and workspace layer. Ollama is the runtime that loads and serves local models. That means your setup sequence should be:
- Install Ollama.
- Run at least one model in Ollama.
- Verify Ollama responds locally.
- Install Open WebUI.
- Connect Open WebUI to Ollama.
- Confirm the model list appears.
- Only then add PDFs, knowledge bases, remote access, or cloud providers.
If Ollama does not work first, Open WebUI will not fix it.
What Open WebUI adds to Ollama
| Layer | Ollama | Open WebUI | Beginner takeaway |
|---|---|---|---|
| Model runtime | Yes | No; it connects to runtimes/providers | Ollama runs the model. Open WebUI gives you the interface. |
| Browser chat interface | Limited/core product is not mainly a browser interface | Yes | Open WebUI is useful if you want a familiar chat surface. |
| Local API backend | Yes | It consumes provider APIs and has its own app APIs | Keep the roles separate. |
| User accounts | Not the beginner focus | Yes, first admin/user setup | Treat auth carefully. |
| File upload/RAG | Usually through paired tools | Yes, depending on configuration | Check storage and embedding provider. |
| Cloud providers | Ollama has local and cloud-related features | Open WebUI can connect to local or cloud providers | Provider choice controls privacy. |
| Docker complexity | Optional | Common install path | Most beginner failures are Docker/networking failures. |
Requirements
Use this checklist before installing.
| Requirement | Why it matters |
|---|---|
| Ollama installed and running | Open WebUI needs a model provider to connect to. |
| At least one Ollama model pulled | Open WebUI cannot show useful local models if Ollama has none. |
| Docker installed | The common Open WebUI install path uses Docker. |
| Enough RAM/storage | You need memory for Ollama, the model, Docker, browser, and Open WebUI. |
| Localhost/network understanding | Docker containers do not always see the host as localhost. |
| Non-sensitive test prompt | Do not use confidential data until the privacy boundary is verified. |
Step 1: Confirm Ollama works first
Before touching Open WebUI, run Ollama directly.
ollama list
If you do not see any models, pull or run a small starter model first. Then confirm the local API responds:
curl http://localhost:11434/api/tags
On Windows PowerShell, you may prefer:
Invoke-WebRequest http://localhost:11434/api/tags
Do not continue until Ollama is responding locally.
Step 2: Choose your Open WebUI install path
Most beginners should use Docker. It is not always the simplest conceptually, but it is the most common documented deployment path and makes updates/persistence more manageable when configured correctly.
| Path | Best for | Caveat |
|---|---|---|
| Docker | Most users following common Open WebUI docs/tutorials | Requires Docker networking and volume understanding. |
| Python/bare metal | Users who prefer not to use Docker | More environment-specific; not the easiest beginner path. |
| Bundled Ollama image | Users who want a containerized all-in-one path | GPU/CPU behavior and persistence must be checked carefully. |
| Remote/server install | Home-lab or team-style users | Security, auth, ports, TLS, and backups matter much more. |
For this beginner article, Docker should be the primary path.
Step 3: Install Open WebUI with Docker
Use the standard Open WebUI image for this guide's chat and later document workflow. The slim image omits local document, embedding, and speech dependencies and requires separate services for those features.
A typical Docker install needs three things:
- The Open WebUI image.
- A persistent volume for app data.
- A way for the container to reach Ollama.
First create a private server key. On macOS or Linux, in a shell with OpenSSL:
webuiSecret=$(openssl rand -hex 32)
In Windows PowerShell instead:
$webuiSecretBytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($webuiSecretBytes)
$webuiSecret = -join ($webuiSecretBytes | ForEach-Object { $_.ToString("x2") })
Keep the generated key in a private place and reuse it when recreating this container. In the same terminal where you set that variable, run this single-line command; the variable syntax works in both the shell and PowerShell examples:
docker run -d --name open-webui -p 127.0.0.1:3000:8080 --add-host=host.docker.internal:host-gateway -e "WEBUI_SECRET_KEY=$webuiSecret" -e OLLAMA_BASE_URL=http://host.docker.internal:11434 -v open-webui:/app/backend/data --restart always ghcr.io/open-webui/open-webui:v0.12.0
The example pins the documented v0.12.0 release. Check the release page before choosing an update. :main and :latest are rolling images; they do not identify an unchanging stable release. The volume keeps app data across container replacement, and the fixed key avoids changing the server identity every time the container is recreated.
After the container starts, open:
http://localhost:3000
The 127.0.0.1 part of the command restricts the published port to this computer. Use Docker Engine 28 or newer: older versions can allow devices on the same network to reach a localhost-published port. Do not remove that address simply to fix a connection problem.
You should see the Open WebUI setup screen.
Step 4: Create the first admin user
On a fresh Open WebUI install, the first account usually becomes the administrator. Use a test account for the first run, not a sensitive production deployment.
| Setup item | Recommendation |
|---|---|
| First account | Use a strong password. |
| Test environment | Use non-sensitive prompts and files. |
| Network exposure | Keep it local until you understand the security model. |
| Backups | Confirm the volume persists before you upload important files. |
Do not expose Open WebUI to the internet just because it works on localhost.
Step 5: Connect Open WebUI to Ollama
This is the part that most often breaks.
If Open WebUI runs directly on the same host, localhost may work. If Open WebUI runs inside Docker, localhost from inside the container usually means the container itself, not the host machine. In many Docker Desktop setups, the host is reached through host.docker.internal.
The command above supplies that hostname and the intended Ollama URL. If the host API works but the container connection is refused, check Ollama's listening address and the host firewall. Do not simply publish Ollama's port to the whole network. A change to OLLAMA_HOST changes which interfaces the service accepts; if your Docker environment requires such a change, restrict access to the intended container through your host's firewall and follow the official platform instructions. If you do not want to manage that boundary, a native Python installation of Open WebUI can connect to host Ollama at http://localhost:11434; use the official quick start for its supported Python version and isolated environment.
| Situation | Ollama URL to investigate | Why |
|---|---|---|
| Open WebUI and Ollama both on the host | http://localhost:11434 | Same local machine context. |
| Open WebUI in Docker, Ollama on host | http://host.docker.internal:11434 | Container needs to reach the host. |
| Linux Docker with host networking | http://localhost:11434 may work with host network | Depends on exact Docker networking. |
| Ollama bound only to localhost but container cannot reach it | Adjust Ollama host binding only if you understand the risk | Network exposure changes security profile. |
Keep this distinction clear:
Browser localhost, container localhost, and host-machine localhost are not always the same place.
Step 6: Confirm models appear
After Open WebUI is connected to Ollama, the model picker should show the models available in Ollama.
If no models appear:
- Confirm Ollama has a model with
ollama list. - Confirm Ollama responds at
http://localhost:11434/api/tagsfrom the host. - Check the Ollama base URL configured inside Open WebUI.
- If Docker is involved, test
host.docker.internal. - Restart the Open WebUI container after changing connection settings.
- Check container logs and Open WebUI settings.
Do not upload files or troubleshoot RAG until the basic model picker works.
Step 7: Run a simple local chat
Start with a trivial prompt:
Write one sentence explaining what local AI is.
Check the model picker and provider connection to confirm the downloaded Ollama model is selected. A reply alone cannot identify which model answered. Then try another prompt:
Give me a three-bullet checklist for choosing a small local model.
Record:
| Setting to keep for troubleshooting | Why |
|---|---|
| Ollama version | Product behavior changes. |
| Open WebUI version/image tag | Docker tags and interface settings change. |
| OS and Docker version | Networking behavior differs. |
| Model identifier | Results depend on model and quantization. |
| Connection URL | Most failures are endpoint-related. |
| First successful local response | Shows that this exact machine, app version, model, and connection path worked. |
Optional: use Open WebUI for PDFs and documents
Open WebUI can support file uploads and knowledge/RAG workflows, but do not treat PDF chat as automatically private or accurate.
Before using sensitive documents, verify:
| Question | Why it matters |
|---|---|
| Which model provider is selected? | A cloud provider sends content outside your local machine. |
| Which embedding provider is selected? | Cloud embeddings can send document text or chunks out. |
Where is DATA_DIR or persistent storage? | Uploaded files, vector data, and settings need a known location. |
| Are web search or external tools enabled? | Tools can change the data boundary. |
| Is the server exposed beyond localhost? | Other devices may be able to reach it. |
For document workflows, read Chat With PDFs Locally before uploading private material.
Common Open WebUI + Ollama problems
| Problem | Likely cause | First fix |
|---|---|---|
| Open WebUI page does not load | Container not running, wrong port, Docker not started | Run docker ps and check port mapping |
| Open WebUI cannot connect to Ollama | Container cannot reach host Ollama | Try the correct host/container URL pattern |
| Models do not appear | Ollama has no models or wrong base URL | Run ollama list and verify Open WebUI provider settings |
| Connection refused | Ollama not running or not reachable from container | Start Ollama; verify API endpoint |
| Works once, then breaks | Container, volume, or provider config changed | Check logs and persisted settings |
| Data disappears after update | No persistent volume was mounted | Use a persistent Docker volume and backup before updates |
| PDF answers are bad | Extraction, chunking, embeddings, retrieval, or model quality issue | Test with a short clean PDF first |
| Private setup sends data to cloud | Cloud model or embedding provider selected | Switch to local provider and retest offline |
Windows notes
Windows users should expect extra setup friction because Docker Desktop and WSL 2 can affect networking. The safest beginner sequence is:
- Install Ollama and confirm it works from Windows.
- Install Docker Desktop.
- Confirm WSL 2 is installed and Docker can run Linux containers.
- Run Open WebUI.
- Test whether Open WebUI can reach Ollama.
- Fix networking before touching PDFs or plugins.
If a tutorial says “just use localhost” and it fails, the problem may be the container boundary, not Open WebUI itself.
Mac notes
On macOS, the common beginner path is:
- Install Ollama for macOS.
- Verify the local API.
- Install Docker Desktop.
- Run Open WebUI.
- Open
http://localhost:3000. - Confirm Open WebUI can see Ollama models.
Do not assume Docker gives GPU acceleration for every Mac workflow. Keep the interface layer and runtime layer conceptually separate: Ollama runs the model; Open WebUI provides the interface.
Linux notes
Linux users may have the cleanest server-style path, but more responsibility:
| Topic | Why it matters |
|---|---|
| Docker permissions | The user may need Docker group access or sudo. |
| Host networking | Linux --network=host behavior differs from Docker Desktop. |
| Firewall | Ports may be blocked locally or on the LAN. |
| Service management | Ollama and Open WebUI may run as separate services/containers. |
| GPU access | NVIDIA/AMD container setup may require extra runtime configuration. |
Linux is powerful, but it is not always the easiest beginner path.
Security and privacy checklist
Before using Open WebUI with real data:
- Confirm the selected model provider is local Ollama.
- Confirm embeddings are local if using documents.
- Keep the service on localhost or a trusted private network.
- Use a strong admin password.
- Do not expose the port to the public internet without a real hardening plan.
- Understand where uploads, vector data, chats, and settings are stored.
- Back up persistent data before updates.
- Disable or avoid features you do not understand, especially cloud providers, web search, plugins, and tools.
- Test offline behavior only after all required models and dependencies are downloaded.
When should you not install Open WebUI yet?
Wait if:
| Situation | Better next step |
|---|---|
| You have not installed Ollama | Read How to Install Ollama. |
| You only want the easiest desktop app | Try How to Install LM Studio. |
| You are on an 8GB machine | Read Best Local AI for 8GB RAM first. |
| You do not understand the privacy boundary | Read Is Local AI Actually Private?. |
| Docker already feels overwhelming | Start with LM Studio before Open WebUI. |
| You need a production/team deployment | Do not use this beginner article as a security hardening guide. |
FAQ
Do I need Ollama before Open WebUI?
For this setup, yes. Open WebUI is the interface and Ollama is the local model runtime. You can connect Open WebUI to other providers, but this article is specifically about Open WebUI with Ollama.
What port does Open WebUI use?
The Docker mapping in this guide makes Open WebUI available at localhost:3000 in the browser while the container listens internally on its own port. Always confirm the exact command you used.
Why can’t Open WebUI see my Ollama models?
Usually because Ollama has no models, Ollama is not running, or Open WebUI is pointing to the wrong Ollama URL. Docker networking is the most common source of confusion.
Should I use localhost or host.docker.internal?
It depends on where Open WebUI is running. From your browser, localhost means your computer. From inside a Docker container, localhost means the container. Many Docker Desktop setups use host.docker.internal to reach services running on the host.
Can Open WebUI run fully locally?
It can be configured for local workflows, but you must check the selected model provider, embedding provider, storage, web-search/tools settings, and network exposure. Do not assume local just because the interface is self-hosted.
Can I chat with PDFs in Open WebUI?
Yes, Open WebUI supports file and knowledge workflows, but accuracy and privacy depend on parsing, embeddings, retrieval settings, model quality, and provider configuration.
Is Open WebUI easier than LM Studio?
Not for a first local AI chat. LM Studio is usually easier as a desktop app. Open WebUI is more attractive once you already have Ollama working and want a browser-based workspace.
What to read next
- How to Install Ollama
- Ollama vs LM Studio
- Best Local AI Setup for Windows
- Best Local AI Setup for Mac
- Chat With PDFs Locally
- Is Local AI Actually Private?
Sources
- Open WebUI quick start, image variants, keys, and provider connection
- Open WebUI v0.12.0 release
- Docker published-port behavior
- Ollama server configuration