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:

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.

Install Open WebUI

Open your terminal and run:

pip install open-webui

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.

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: {}

Start the services

Run the following command:

docker compose up -d

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.

​Installing Open WebUI

​Installation Methods

Docker

Python pip

Docker Compose

Kubernetes

​Docker Installation

​Prerequisites

​With Local Ollama

​With Remote Ollama

​With GPU Support (NVIDIA)

​OpenAI API Only

​Bundled with Ollama

​Python pip Installation

​With PostgreSQL Support

​With All Optional Dependencies

​Docker Compose

​Kubernetes

​Environment Configuration

​Network Configuration

​Using Host Network

​Using Dev Branch

​Offline Mode

​Environment Variables

​Next Steps

Quick Start

Configuration

​Troubleshooting

Installing Open WebUI

Installation Methods

Docker Installation

Prerequisites

With Local Ollama

With Remote Ollama

With GPU Support (NVIDIA)

OpenAI API Only

Bundled with Ollama

Python pip Installation

With PostgreSQL Support

With All Optional Dependencies

Docker Compose

Kubernetes

Environment Configuration

Network Configuration

Using Host Network

Using Dev Branch

Offline Mode

Environment Variables

Next Steps

Troubleshooting