Installation

Complete installation guide for Open WebUI using Docker, pip, and Kubernetes

Installing Open WebUI

Open WebUI supports multiple installation methods to suit your deployment needs. Choose the method that best fits your infrastructure and requirements.

Before installing, ensure you’re using Python 3.11 or 3.12 for pip installations. Docker installations work on any system with Docker installed.

Installation Methods

Docker

Recommended for most users - quick and isolated

Python pip

Direct installation using Python package manager

Docker Compose

Multi-container setup with Ollama included

Kubernetes

Production deployments with kubectl, kustomize, or helm

---

Docker Installation

Docker is the recommended installation method for most users, providing isolation and easy management.

When using Docker to install Open WebUI, make sure to include the -v open-webui:/app/backend/data in your Docker command. This step is crucial as it ensures your database is properly mounted and prevents any loss of data.

Prerequisites

• Docker installed on your system
• (Optional) NVIDIA CUDA container toolkit for GPU support

With Local Ollama

If Ollama is running on your computer:

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

Access Open WebUI at http://localhost:3000

With Remote Ollama

If Ollama is on a different server:

docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=https://example.com \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

With GPU Support (NVIDIA)

To run Open WebUI with Nvidia GPU support:

You must install the Nvidia CUDA container toolkit on your Linux/WSL system before using the :cuda image.

docker run -d -p 3000:8080 \
  --gpus all \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:cuda

OpenAI API Only

If you’re only using OpenAI API:

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

Bundled with Ollama

This installation method uses a single container image that bundles Open WebUI with Ollama:

With 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

---

Python pip Installation

Install Open WebUI directly using pip for development or custom deployments.

Before proceeding, ensure you’re using Python 3.11 or 3.12 to avoid compatibility issues.

1. Install Open WebUI

   Open your terminal and run:

   pip install open-webui
   
2. Run Open WebUI

   After installation, start the server:

   open-webui serve
   

   The server will start and be accessible at http://localhost:8080

With PostgreSQL Support

To install with PostgreSQL support:

pip install open-webui[postgres]

With All Optional Dependencies

For a complete installation with all optional features:

pip install open-webui[all]

---

Docker Compose

Docker Compose provides a convenient way to run Open WebUI with Ollama in a multi-container setup.

1. Create docker-compose.yaml

   Create a docker-compose.yaml file with the following content:

   services:
     ollama:
       volumes:
         - ollama:/root/.ollama
       container_name: ollama
       pull_policy: always
       tty: true
       restart: unless-stopped
       image: ollama/ollama:latest
   
     open-webui:
       image: ghcr.io/open-webui/open-webui:main
       container_name: open-webui
       volumes:
         - open-webui:/app/backend/data
       depends_on:
         - ollama
       ports:
         - 3000:8080
       environment:
         - 'OLLAMA_BASE_URL=http://ollama:11434'
         - 'WEBUI_SECRET_KEY='
       extra_hosts:
         - host.docker.internal:host-gateway
       restart: unless-stopped
   
   volumes:
     ollama: {}
     open-webui: {}
   
2. Start the services

   Run the following command:

   docker compose up -d
   
3. Access Open WebUI

   Open your browser and navigate to http://localhost:3000

---

Kubernetes

Deploy Open WebUI in Kubernetes for production-grade scalability and reliability.

Kubernetes deployments support kubectl, kustomize, and Helm. Refer to the Open WebUI documentation for detailed Kubernetes deployment guides.

Environment Configuration

For Kubernetes deployments, set the K8S_FLAG environment variable:

env:
  - name: K8S_FLAG
    value: "true"
  - name: OLLAMA_BASE_URL
    value: "http://ollama-service.open-webui.svc.cluster.local:11434"

---

Network Configuration

Using Host Network

If you’re experiencing connection issues, use the --network=host flag. Note that the port changes from 3000 to 8080:

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

Access at http://localhost:8080

---

Using Dev Branch

The :dev branch contains the latest unstable features and changes. Use it at your own risk as it may have bugs or incomplete features.

To try bleeding-edge features:

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

---

Offline Mode

If running Open WebUI in an offline environment, set the HF_HUB_OFFLINE environment variable:

export HF_HUB_OFFLINE=1

Or in Docker:

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

---

Environment Variables

Key environment variables for installation:

Variable	Description	Default
OLLAMA_BASE_URL	URL for Ollama server	http://localhost:11434
OPENAI_API_KEY	OpenAI API key	-
OPENAI_API_BASE_URL	OpenAI API base URL	-
WEBUI_SECRET_KEY	Secret key for sessions	Generated
DATA_DIR	Data directory path	/app/backend/data
HF_HUB_OFFLINE	Offline mode for HuggingFace	false

See the Configuration Guide for a complete list of environment variables.

---

Next Steps

Quick Start

Get started with your first chat

Configuration

Configure Open WebUI settings

Troubleshooting

Connection Issues

If you experience connection issues, the WebUI docker container may not be able to reach the Ollama server. Try using --network=host or verify your OLLAMA_BASE_URL setting.

Data Persistence

Always use volume mounts (-v open-webui:/app/backend/data) to ensure data persistence across container restarts.

GPU Not Detected

Ensure the NVIDIA CUDA container toolkit is properly installed and use the :cuda tagged image.

For more troubleshooting help, visit the Open WebUI Documentation or join our Discord community.