open-webui

library0.8.12pypypiunverified

Open WebUI is an extensible, feature-rich, and user-friendly self-hosted AI platform designed to operate entirely offline. It supports various Large Language Model (LLM) runners, including Ollama and OpenAI-compatible APIs, with built-in inference engine for RAG. It provides a ChatGPT-style interface for interacting with local or cloud-based models. The project is actively developed with continuous updates.

llm-agents web-framework ai-ml

pip install open-webui

package ↗homepage ↗

INSTALL

IMPORT

SIG · OPEN-WEBUI

open-webui

llm-agentspythonv0.8.12

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Install Open WebUI via pip and then start the web server. The UI will typically be accessible at http://localhost:8080 (or http://localhost:3000 if using Docker without --network=host).

pip install open-webui open-webui serve

Debug

Known issues

breakingWhen using Docker, the `:main` tag always points to the latest build and can include breaking changes without warning. For production or stability, it is recommended to pin a specific version tag (e.g., `:v0.8.6`).

fix

Use a specific version tag (e.g., `ghcr.io/open-webui/open-webui:v0.8.12`) instead of `:main` in Docker commands.

affects: All versions using `:main` Docker tag

gotchaA persistent `WEBUI_SECRET_KEY` environment variable is crucial. Without it, Open WebUI generates a random key on each restart, leading to user logouts and 'Error decrypting tokens' for essential secrets like OAuth tokens or API keys.

fix

Set a persistent `WEBUI_SECRET_KEY` environment variable in your deployment environment.

affects: All versions

gotchaEnsure you are using Python 3.11 for installation to avoid compatibility issues. The library requires Python <3.13.0a1,>=3.11.

fix

Use `python=3.11` when creating virtual environments (e.g., `conda create -n open-webui python=3.11`) or ensure your system default is 3.11.

affects: <0.8.12

gotchaFor Docker deployments with Ollama, connection issues often arise if the WebUI container cannot reach the Ollama server. Using `--network=host` and setting `OLLAMA_BASE_URL` (e.g., `http://127.0.0.1:11434`) in your Docker run command can resolve this.

fix

Add `--network=host` and `-e OLLAMA_BASE_URL=http://127.0.0.1:11434` to your `docker run` command.

affects: All versions

gotchaEnabling `ENABLE_REALTIME_CHAT_SAVE` in production is strongly discouraged. It causes massive database write pressure and severe performance degradation under concurrent load.

fix

Ensure `ENABLE_REALTIME_CHAT_SAVE` is set to `False` (or not set, as `False` is the default) in production environments.

affects: All versions

gotchaAfter updating Open WebUI, it's a common issue that the UI might appear broken due to stale frontend assets.

fix

Clear your browser cache (Ctrl+F5 or Cmd+Shift+R) after updating.

affects: All versions

gotchaWorkspace Tools and Functions execute arbitrary Python code on your server. Restrict Workspace access to trusted administrators only, as granting tool creation/import access is equivalent to giving shell access.

fix

Review and restrict user permissions for 'Workspace → Tools' to trusted administrators.

affects: All versions with Workspace Tools/Functions

Errors

Common errors & fixes

Open WebUI: Server Connection Error / Connection refused / Cannot connect to host host.docker.internal:11434

This error commonly occurs when Open WebUI, especially when running in a Docker container, cannot reach the Ollama server. This is often due to Ollama only listening on `127.0.0.1` (localhost) on the host machine, which is not directly accessible from within the Docker container, or incorrect network configuration.

fix

Ensure Ollama is configured to listen on all network interfaces by setting `OLLAMA_HOST=0.0.0.0` in its environment variables and restarting it. When running Open WebUI in Docker, use the `--network=host` flag to allow the container to access the host's network, or configure `OLLAMA_BASE_URL` to `http://host.docker.internal:11434` and ensure `host.docker.internal` is resolvable within the Docker container (e.g., by adding `--add-host=host.docker.internal:host-gateway` to the `docker run` command).

No models available / models not showing in the UI

This typically happens when Open WebUI cannot successfully communicate with the Ollama server to retrieve the list of available models, or when the `OLLAMA_BASE_URL` is incorrectly configured within Open WebUI's settings or environment variables. It can also be due to non-admin users lacking permissions to see models, or Ollama itself not having any models pulled.

fix

First, ensure Ollama is running and has models pulled (run `ollama list` in your terminal). Verify that the `OLLAMA_BASE_URL` environment variable for Open WebUI is correctly set to the address where Ollama is accessible (e.g., `http://127.0.0.1:11434` or `http://host.docker.internal:11434` if in Docker). If running in Docker, ensure proper network configuration as described in the 'Connection refused' fix. Also, check Open WebUI's Admin Settings > Connections to confirm the Ollama Server URL is correct, and for non-admin users, ensure model access control is configured appropriately or temporarily set `BYPASS_MODEL_ACCESS_CONTROL` environment variable.

500 Internal Server Error (Ollama: 500, message='Internal Server Error') when generating responses

This error often indicates that the loaded model requires more RAM than is currently available on the system running Ollama. When a model attempts to load or process a request, and there isn't enough memory, Ollama can return an internal server error.

fix

Reduce the size of the model being used, or free up system RAM. To determine the memory requirements of a model, you can run `ollama run <model_name>` in your terminal. If continuously encountering this, consider upgrading your system's RAM or using a machine with more memory. You can also adjust the `AIOHTTP_CLIENT_TIMEOUT` environment variable in Open WebUI to increase the timeout for slow responses, though this does not fix the underlying memory issue.

Upgrade

Version history

0.8.12latest on PyPI · released Mar 27, 2026

Audit

Dependencies

PythonrequiredRequires Python 3.11 or newer (up to <3.13.0a1) for compatibility.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/open-webui/ ↗

homepagehttps://openwebui.com ↗