快速开始

在您的机器上运行 Open WebUI。请在下方选择您偏好的安装方法。

Open WebUI 适用于 macOS、Linux（x86_64 和 ARM64，包括树莓派和 NVIDIA DGX Spark）以及 Windows。

• Docker: 官方支持，且面向大多数用户的推荐方式。需要先安装 Docker。
• Python: 适用于低资源环境或手动安装。
• Kubernetes: 适用于需要进行扩展和编排的企业部署。

Docker

Docker

使用 Docker 快速开始

信息

需要 WebSocket 支持。请确保您的网络配置允许 WebSocket 连接。

Docker Hub 现已可用

Open WebUI 镜像同时发布在两个镜像托管服务中：

• GitHub Container Registry: ghcr.io/open-webui/open-webui
• Docker Hub: openwebui/open-webui

两者包含完全相同的镜像。在下方的任何命令中，您都可以将 ghcr.io/open-webui/open-webui 替换为 openwebui/open-webui。

1. 拉取镜像

docker pull ghcr.io/open-webui/open-webui:main

2. 运行容器

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

参数	用途
-v open-webui:/app/backend/data	持久化存储。防止容器重启时数据丢失。
-p 3000:8080	将 UI 界面映射到您机器的 3000 端口。

3. 打开 UI 界面

访问 http://localhost:3000。

---

镜像变体

标签 (Tag)	适用场景
:main	标准镜像 (推荐)
:main-slim	较小的镜像，会在首次使用时下载 Whisper 和嵌入（embedding）模型
:cuda	支持 Nvidia GPU (需要在 docker run 命令中添加 --gpus all 参数)
:ollama	将 Ollama 打包集成在容器中以实现全功能合一的配置

特定发布版本

对于生产环境，我们建议锁定到特定的版本，而不是使用浮动的镜像标签：

docker pull ghcr.io/open-webui/open-webui:v0.9.5
docker pull ghcr.io/open-webui/open-webui:v0.9.5-cuda
docker pull ghcr.io/open-webui/open-webui:v0.9.5-ollama

---

常见配置

GPU 支持 (Nvidia)

docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda

与 Ollama 打包

在一个容器中同时集成 Open WebUI 和 Ollama：

使用 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

仅使用 CPU：

docker run -d -p 3000:8080 -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

连接到其他服务器上的 Ollama

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

单用户模式 (无登录)

docker run -d -p 3000:8080 -e WEBUI_AUTH=False -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

警告

在此更改之后，您无法在单用户模式和多账户模式之间进行切换。

---

使用 Dev 开发分支

提示

测试 dev 构建版本是极其有价值的贡献方式。您可以在测试实例上运行它，并在 GitHub 上反馈问题。

:dev 标签包含了在发布稳定版之前的最新功能。

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev

警告

切勿在开发版和生产版之间共享您的数据卷。 开发版中可能包含不向下兼容的数据库迁移。请务必使用独立的数据卷（例如 -v open-webui-dev:/app/backend/data）。

如果您不希望使用 Docker，请参考 开发 Open WebUI 指南。

---

卸载

1. 停止并移除容器：

   docker rm -f open-webui

2. 移除镜像 (可选)：

   docker rmi ghcr.io/open-webui/open-webui:main

3. 移除数据卷 (可选，这会删除所有数据)：

   docker volume rm open-webui

更新

若要将您本地的 Docker 安装更新到最新版本，您可以使用 Watchtower 或手动更新容器。

选项 1：使用 Watchtower

通过使用 Watchtower，您可以使更新过程自动化：

docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once open-webui

(如果您的容器名称不同，请将 open-webui 替换为您实际的容器名称。)

选项 2：手动更新

1. 停止并移除当前的容器：

   docker rm -f open-webui

2. 拉取最新版本的镜像：

   docker pull ghcr.io/open-webui/open-webui:main

3. 重新启动容器：

   docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
     -e WEBUI_SECRET_KEY="your-secret-key" \
     --name open-webui --restart always \
     ghcr.io/open-webui/open-webui:main

设置 WEBUI_SECRET_KEY

如果没有配置持久化的 WEBUI_SECRET_KEY，每次重建容器时，您都将被强制退出登录。可以使用 openssl rand -hex 32 命令生成一个秘钥。

有关版本锁定、回滚、自动更新工具和备份流程，请参阅完整更新指南。

Docker Compose

Docker Compose 安装

使用 Docker Compose 可以简化多容器 Docker 应用程序的管理。

Docker Compose 需要额外的安装包 docker-compose-v2。

警告

较旧的 Docker Compose 教程可能会参考版本 1 的语法，该语法使用类似于 docker-compose build 的命令。请确保使用版本 2 的语法，即使用 docker compose build 这样的命令（注意是空格而不是连字符）。

docker-compose-v2 示例

这里有一个使用 Docker Compose 配置安装 Open WebUI 的示例文件：

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

使用 Slim 镜像

对于存储空间或带宽有限的环境，您可以使用不包含预打包模型的 slim 镜像变体：

services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main-slim
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:

说明

Slim 镜像将在首次使用时下载必需的模型（如 Whisper、向量化模型），这可能会导致较长的首次启动时间，但会显著减小镜像大小。

启动服务

要启动您的服务，请运行以下命令：

docker compose up -d

助手脚本

代码库中包含一个名为 run-compose.sh 的实用助手脚本。该脚本可以协助您选择在部署中包含哪些 Docker Compose 文件，从而简化配置流程。

---

说明

若要获取 Nvidia GPU 支持，请将镜像从 ghcr.io/open-webui/open-webui:main 更改为 ghcr.io/open-webui/open-webui:cuda，并在 docker-compose.yml 文件的服务定义中添加以下内容：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

此配置可确保您的应用程序在 GPU 资源可用时能够加以利用。

卸载

若要卸载以 Docker Compose 运行的 Open WebUI，请遵循以下步骤：

1. 停止并移除服务： 在包含 docker-compose.yml 文件的目录中运行以下命令：

   docker compose down

2. 移除卷（可选，警告：这会删除所有数据）： 如果您希望完全删除您的数据（对话、设置等）：

   docker compose down -v

   或者手动删除：

   docker volume rm <your_project_name>_open-webui

3. 移除镜像（可选）：

   docker rmi ghcr.io/open-webui/open-webui:main

Extension 扩展

Docker Desktop 扩展

Docker 官方已经发布了一个使用 Docker Model Runner 进行推理的 Open WebUI Docker 扩展。您可以在此处阅读他们的入门博客：Run Local AI with Open WebUI + Docker Model Runner。

您可以在其 GitHub 仓库中找到该扩展的排错步骤：Open WebUI Docker Extension - Troubleshooting。

虽然这是以较低摩擦力尝试体验 Open WebUI 的绝佳资源，但它并不是官方支持的安装方法——在使用它时，您可能会遇到未预期的 Bug 或行为。例如，您无法在扩展中登录为不同的用户，因为它是专门针对单个本地用户设计的。如果您在使用该扩展时遇到问题，请在扩展的 GitHub 仓库 中提交 Issue。

Podman

使用 Podman

Podman 是一个用于开发、管理和运行 OCI 容器的无守护进程（Daemonless）容器引擎。

基础命令

• 运行容器：

  podman run -d --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main

• 列出正在运行的容器：

  podman ps

Podman 网络

如果遇到网络问题（特别是在 rootless 模式的 Podman 上），您可能需要调整网桥设置。

Slirp4netns 废弃警告

较旧的 Podman 说明通常推荐使用 slirp4netns。然而，slirp4netns 目前已被废弃，并将在 Podman 6 中被彻底移除。

其现代替代方案是 pasta，这已是 Podman 5.0+ 中的默认网络驱动。

访问宿主机（本地服务）

如果您的宿主机上直接运行了 Ollama 或其他服务，请使用特殊的 DNS 名称 host.containers.internal 来指向您的计算机。

现代方法（Pasta - Podman 5+ 中的默认设置）

通常无需任何特殊参数，即可通过 host.containers.internal 访问宿主机。

传统方法（Slirp4netns）

如果您使用的是较旧版本的 Podman 且 pasta 不可用：

1. 确保您已经 安装了 slirp4netns。
2. 使用以下参数启动容器以允许主机回环（Loopback）：

podman run -d --network=slirp4netns:allow_host_loopback=true --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main

连接配置

进入 Open WebUI 后，转到 设置 > 管理员设置 > 外部连接，并将您的 Ollama API 连接设置为： http://host.containers.internal:11434

有关高级配置，请参阅 Podman 官方文档。

卸载

若要卸载以 Podman 运行的 Open WebUI，请遵循以下步骤：

1. 停止并移除容器：

   podman rm -f openwebui

2. 移除镜像（可选）：

   podman rmi ghcr.io/open-webui/open-webui:main

3. 移除卷（可选，警告：这会删除所有数据）： 如果您希望完全删除您的数据（对话、设置等）：

   podman volume rm open-webui

Quadlets

Podman Quadlets (systemd)

Podman Quadlets 允许您将容器作为原生的 systemd 服务进行管理。对于使用 systemd 的 Linux 发行版（如 Fedora, RHEL, Ubuntu 等），这是在生产环境中运行容器的推荐方式。

🛠️ 安装配置

1. 创建配置目录： 对于非 root 用户的无特权部署（Rootless）：

   mkdir -p ~/.config/containers/systemd/

2. 创建容器配置文件： 创建一个名为 ~/.config/containers/systemd/open-webui.container 的文件，其内容如下：

   [Unit]
   Description=Open WebUI Container
   After=network-online.target
   
   [Container]
   Image=ghcr.io/open-webui/open-webui:main
   ContainerName=open-webui
   PublishPort=3000:8080
   Volume=open-webui:/app/backend/data
   
   # 网络：Pasta 是 Podman 5+ 中的默认网络驱动
   # 如果您需要访问宿主机上的服务（如宿主机上的 Ollama）：
   AddHost=host.containers.internal:host-gateway
   
   [Service]
   Restart=always
   
   [Install]
   WantedBy=default.target

3. 重载 systemd 并启动服务：

   systemctl --user daemon-reload
   systemctl --user start open-webui

4. 启用开机自启：

   systemctl --user enable open-webui

📊 状态管理

• 检查状态：

  systemctl --user status open-webui

• 查看日志：

  journalctl --user -u open-webui -f

• 停止服务：

  systemctl --user stop open-webui

更新镜像

若要更新镜像，只需拉取新版本（podman pull ghcr.io/open-webui/open-webui:main）并重启该服务（systemctl --user restart open-webui）。

Kube Play

Podman Kube Play 安装

Podman 支持类 Kubernetes 的语法，可用于部署诸如 Pod、挂载卷等资源，而无需承受部署完整 Kubernetes 集群的系统开销。请参见 Kube Play 官方介绍。

如果您尚未安装 Podman，请访问 Podman 官方网站。

play.yaml 示例

这里有一个使用 Podman Kube Play 部署的文件示例：

apiVersion: v1
kind: Pod
metadata:
  name: open-webui
spec:
  containers:
    - name: container
      image: ghcr.io/open-webui/open-webui:main
      ports:
        - name: http
          containerPort: 8080
          hostPort: 3000
      volumeMounts:
        - mountPath: /app/backend/data
          name: data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName:  open-webui-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: open-webui-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

启动

要启动您的 Pod，请运行以下命令：

podman kube play ./play.yaml

使用 GPU 支持

为了获取 Nvidia GPU 支持，您需要将容器镜像替换为 ghcr.io/open-webui/open-webui:cuda，并在 Pod 资源的限制中指定所需的设备（GPU），如下所示：

      [...]
      resources:
        limits:
          nvidia.com/gpu=all: 1
      [...]

重要提示

为了让 open-webui 容器成功访问 GPU，您需要在您的 Podman 机器中安装要访问的 GPU 所对应的容器设备接口（Container Device Interface, CDI）。您可以阅读 Podman GPU 容器访问指南 了解更多细节。

Swarm

Docker Swarm

此安装方法需要具备 Docker Swarm 相关的知识，因为它利用了 Stack 文件将 3 个独立的容器作为服务部署在 Docker Swarm 中。

它包含各自独立的 ChromaDB、Ollama 和 OpenWebUI 容器。 此外，其中还预填了环境变量以进一步说明该配置。

为什么 ChromaDB 需要作为一个独立的容器运行

此 Stack 将 ChromaDB 正确地部署为一个独立的 HTTP 服务器容器，Open WebUI 通过 CHROMA_HTTP_HOST 和 CHROMA_HTTP_PORT 与之连接。这对于任何多 Worker 或多副本部署都是必需的。

默认的 ChromaDB 模式（不带 CHROMA_HTTP_HOST）使用的是本地 SQLite 支持的 PersistentClient，这不是 fork 安全的——来自多个 Worker 进程的并发写入会使 Uvicorn Worker 瞬间崩溃。将 ChromaDB 作为独立服务器运行可以通过使用 HTTP 连接而不是直接访问 SQLite 来避免此问题。

如果您计划将 openWebUI 服务扩展到多个副本，您还应该为主数据库切换到 PostgreSQL 并设置 Redis。有关完整要求，请参阅 扩展与高可用指南。

请根据您的硬件配置选择合适的命令：

• 在开始之前：

  需要在宿主机上创建挂载卷所对应的目录，或者您可以指定自定义路径或卷。

  当前示例利用了一个独立的目录 data，该目录位于与 docker-stack.yaml 相同的目录下。

  • 例如：

    mkdir -p data/open-webui data/chromadb data/ollama

• 获取 GPU 支持：

docker-stack.yaml

version: '3.9'

services:
  openWebUI:
    image: ghcr.io/open-webui/open-webui:main
    depends_on:
      - chromadb
      - ollama
    volumes:
      - ./data/open-webui:/app/backend/data
    environment:
      DATA_DIR: /app/backend/data
      OLLAMA_BASE_URLS: http://ollama:11434
      CHROMA_HTTP_PORT: 8000
      CHROMA_HTTP_HOST: chromadb
      CHROMA_TENANT: default_tenant
      VECTOR_DB: chroma
      WEBUI_NAME: Awesome ChatBot
      CORS_ALLOW_ORIGIN: "*" # 这是当前的默认值，在上线前需要修改
      RAG_EMBEDDING_ENGINE: ollama
      RAG_EMBEDDING_MODEL: nomic-embed-text-v1.5
      RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE: "True"
    ports:
      - target: 8080
        published: 8080
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3

  chromadb:
    hostname: chromadb
    image: chromadb/chroma:0.5.15
    volumes:
      - ./data/chromadb:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
      - ALLOW_RESET=TRUE
      - PERSIST_DIRECTORY=/chroma/chroma
    ports:
      - target: 8000
        published: 8000
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    healthcheck:
      test: ["CMD-SHELL", "curl localhost:8000/api/v1/heartbeat || exit 1"]
      interval: 10s
      retries: 2
      start_period: 5s
      timeout: 10s

  ollama:
    image: ollama/ollama:latest
    hostname: ollama
    ports:
      - target: 11434
        published: 11434
        mode: overlay
    deploy:
      resources:
        reservations:
          generic_resources:
            - discrete_resource_spec:
                kind: "NVIDIA-GPU"
                value: 0
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    volumes:
      - ./data/ollama:/root/.ollama

• 其他要求：

  1. 确保已启用 CUDA，请遵循您的操作系统和 GPU 指南。
  2. 启用 Docker GPU 支持，请参见 Nvidia Container Toolkit。
  3. 遵循 关于配置 Docker Swarm 以配合您的 GPU 的指南。
  • 确保在 /etc/nvidia-container-runtime/config.toml 中启用了 GPU Resource，并通过取消注释 swarm-resource = "DOCKER_RESOURCE_GPU" 来启用 GPU 资源通告。更新每个节点上的这些文件后，必须重启 Docker 守护进程。

• 仅使用 CPU：

  修改 docker-stack.yaml 中的 Ollama 服务，删除包含 generic_resources: 的行：

      ollama:
    image: ollama/ollama:latest
    hostname: ollama
    ports:
      - target: 11434
        published: 11434
        mode: overlay
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
        max_attempts: 3
    volumes:
      - ./data/ollama:/root/.ollama

• 部署 Docker Stack：

  docker stack deploy -c docker-stack.yaml -d super-awesome-ai

WSL

在 WSL (Windows Subsystem for Linux) 中使用 Docker

本指南提供在 Windows Subsystem for Linux (WSL) 环境中配置 Docker 并运行 Open WebUI 的说明。

步骤 1：安装 WSL

如果您尚未安装 WSL，请参考 Microsoft 官方文档进行安装：

安装 WSL

步骤 2：安装 Docker Desktop

在 WSL 环境中，安装 Docker Desktop 是让 Docker 运行最简单的方式。它会自动处理 Windows 和 WSL 之间的集成。

1. 下载 Docker Desktop： https://www.docker.com/products/docker-desktop/

2. 安装 Docker Desktop： 遵循安装说明，并确保在安装过程中选择 "WSL 2" 作为后端引擎。

步骤 3：为 WSL 配置 Docker Desktop

1. 打开 Docker Desktop： 启动 Docker Desktop 应用程序。

2. 启用 WSL 集成：

   • 转到 Settings > Resources > WSL Integration（设置 > 资源 > WSL 集成）。
   • 确保勾选 "Enable integration with my default WSL distro"（启用与默认 WSL 发行版的集成）。
   • 如果您使用的是非默认的 WSL 发行版，请从列表中选择它并启用。

步骤 4：运行 Open WebUI

现在，您可以在 WSL 终端中遵循标准 Docker 指令来运行 Open WebUI。

docker pull ghcr.io/open-webui/open-webui:main
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

重要注意事项

• 在 WSL 中运行 Docker 命令： 请始终在您的 WSL 终端中运行 docker 命令，而不是在 Windows 的 PowerShell 或命令提示符 (CMD) 中运行。

• 文件系统访问： 当使用数据卷挂载 (-v) 时，请确保路径可以从您的 WSL 发行版中访问。

Python

pip

使用 pip 安装

这是使用 Python 安装 Open WebUI 最简单的方式。

1. 安装 Open WebUI

pip install open-webui

2. 启动服务器

open-webui serve

Open WebUI 现在在 http://localhost:8080 运行。

提示：“open-webui: command not found” 报错？

1. 如果您使用了虚拟环境，请确保它已被激活。
2. 尝试直接运行：python -m open_webui serve
3. 将数据存储在特定的位置：DATA_DIR=./data open-webui serve

卸载

1. 卸载软件包：

   pip uninstall open-webui

2. 清除数据 (可选，这会删除所有数据)：

   rm -rf ~/.open-webui

使用 Python 更新

若要使用 pip 将您本地安装的 Open WebUI 软件包更新到最新版本，请遵循以下简单步骤：

pip install -U open-webui

-U（或 --upgrade）参数可确保 pip 将该软件包升级到最新的可用版本。

升级后，请重新启动服务器并验证其是否正确启动：

open-webui serve

多 Worker 环境警告

如果您运行的 Open WebUI 设置了 UVICORN_WORKERS > 1（例如，在生产环境中），您必须确保更新的数据迁移首先在单个 Worker 上运行，以防止数据库 Schema 损坏。

正确的更新步骤：

1. 使用 pip 更新 open-webui。
2. 启动应用程序时，设置环境变量 UVICORN_WORKERS=1。
3. 等待应用程序完全启动并完成所有数据迁移。
4. 停止并重新启动应用程序，还原为您期望的 Worker 数量。

有关版本锁定、回滚和备份流程，请参阅完整更新指南。

uv

使用 uv 安装

uv 运行时管理器可确保像 Open WebUI 这样的应用程序能够无缝地进行 Python 环境管理。请遵循以下步骤开始使用：

1. 安装 uv

根据您的操作系统选择合适的安装命令：

• macOS/Linux：

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 运行 Open WebUI

一旦安装了 uv，运行 Open WebUI 就会变得非常简单。使用以下命令，务必设置 DATA_DIR 环境变量以避免数据丢失。以下是各个平台的数据路径示例：

• macOS/Linux：

  DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

• Windows (PowerShell)：

  $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve

为什么要设置 DATA_DIR？

设置 DATA_DIR 可以确保您的对话和设置被保存在可预期的位置。如果不设置它，uvx 可能会将其存储在临时文件夹中，而该文件夹在进程结束时会被自动删除。

卸载

若要移除以 uvx 运行的 Open WebUI：

1. 停止服务器： 在运行服务器的终端中按下 Ctrl+C。

2. 从 UV 中卸载： 输入 uv tool uninstall open-webui

3. 可用的清理命令： uvx 命令会以临时或从缓存中运行的方式执行应用程序。若要移除缓存的组件：

   uv cache clean

4. 清除数据 (警告：这会删除所有数据)： 删除您的数据目录（默认为 ~/.open-webui 或您在 DATA_DIR 中设置的路径）：

   rm -rf ~/.open-webui

使用 Python 更新

若要使用 pip 将您本地安装的 Open WebUI 软件包更新到最新版本，请遵循以下简单步骤：

pip install -U open-webui

-U（或 --upgrade）参数可确保 pip 将该软件包升级到最新的可用版本。

升级后，请重新启动服务器并验证其是否正确启动：

open-webui serve

多 Worker 环境警告

如果您运行的 Open WebUI 设置了 UVICORN_WORKERS > 1（例如，在生产环境中），您必须确保更新的数据迁移首先在单个 Worker 上运行，以防止数据库 Schema 损坏。

正确的更新步骤：

1. 使用 pip 更新 open-webui。
2. 启动应用程序时，设置环境变量 UVICORN_WORKERS=1。
3. 等待应用程序完全启动并完成所有数据迁移。
4. 停止并重新启动应用程序，还原为您期望的 Worker 数量。

有关版本锁定、回滚和备份流程，请参阅完整更新指南。

Conda

使用 Conda 安装

1. 创建 Conda 环境：

   conda create -n open-webui python=3.11

2. 激活环境：

   conda activate open-webui

3. 安装 Open WebUI：

   pip install open-webui

4. 启动服务器：

   open-webui serve

提示：“open-webui: command not found” 报错？

如果您的终端提示该命令不存在：

1. 确保您的 Conda 环境已经被激活 (conda activate open-webui)。
2. 如果激活后依然报错，请尝试直接通过 Python 运行：python -m open_webui serve。
3. 如果您希望将数据存储在特定的位置，可以使用：
   • Linux/Mac: DATA_DIR=./data open-webui serve
   • Windows (PowerShell): $env:DATA_DIR=".\data"; open-webui serve

卸载

1. 移除 Conda 环境：

   conda remove --name open-webui --all

2. 清除数据 (警告：这会删除所有数据)： 删除您的数据目录（若无特别配置，默认通常为 ~/.open-webui）：

   rm -rf ~/.open-webui

使用 Python 更新

若要使用 pip 将您本地安装的 Open WebUI 软件包更新到最新版本，请遵循以下简单步骤：

pip install -U open-webui

-U（或 --upgrade）参数可确保 pip 将该软件包升级到最新的可用版本。

升级后，请重新启动服务器并验证其是否正确启动：

open-webui serve

多 Worker 环境警告

如果您运行的 Open WebUI 设置了 UVICORN_WORKERS > 1（例如，在生产环境中），您必须确保更新的数据迁移首先在单个 Worker 上运行，以防止数据库 Schema 损坏。

正确的更新步骤：

1. 使用 pip 更新 open-webui。
2. 启动应用程序时，设置环境变量 UVICORN_WORKERS=1。
3. 等待应用程序完全启动并完成所有数据迁移。
4. 停止并重新启动应用程序，还原为您期望的 Worker 数量。

有关版本锁定、回滚和备份流程，请参阅完整更新指南。

Venv

使用虚拟环境

使用 venv 创建隔离的 Python 环境。

Venv 步骤

1. 创建虚拟环境：

   python3 -m venv venv

2. 激活虚拟环境：

   • 在 Linux/macOS 上：

     source venv/bin/activate

   • 在 Windows 上：

     venv\Scripts\activate

3. 安装 Open WebUI：

   pip install open-webui

4. 启动服务器：

   open-webui serve

提示：“open-webui: command not found” 报错？

如果您的终端提示该命令不存在：

1. 确保您的虚拟环境已经被激活（参见步骤 2）。
2. 如果激活后依然报错，请尝试直接通过 Python 运行：python -m open_webui serve。
3. 如果您希望将数据存储在特定的位置，请使用：DATA_DIR=./data open-webui serve。

卸载

1. 删除虚拟环境： 直接删除 venv 文件夹：

   rm -rf venv

2. 清除数据 (警告：这会删除所有数据)： 删除您的数据目录（若无特别配置，默认通常为 ~/.open-webui）：

   rm -rf ~/.open-webui

使用 Python 更新

若要使用 pip 将您本地安装的 Open WebUI 软件包更新到最新版本，请遵循以下简单步骤：

pip install -U open-webui

-U（或 --upgrade）参数可确保 pip 将该软件包升级到最新的可用版本。

升级后，请重新启动服务器并验证其是否正确启动：

open-webui serve

多 Worker 环境警告

如果您运行的 Open WebUI 设置了 UVICORN_WORKERS > 1（例如，在生产环境中），您必须确保更新的数据迁移首先在单个 Worker 上运行，以防止数据库 Schema 损坏。

正确的更新步骤：

1. 使用 pip 更新 open-webui。
2. 启动应用程序时，设置环境变量 UVICORN_WORKERS=1。
3. 等待应用程序完全启动并完成所有数据迁移。
4. 停止并重新启动应用程序，还原为您期望的 Worker 数量。

有关版本锁定、回滚和备份流程，请参阅完整更新指南。

Kubernetes

Helm

Kubernetes 中的 Helm 安装配置

Helm 可协助您管理 Kubernetes 应用程序。

前提条件

• Kubernetes 集群已配置好。
• 已安装 Helm。

Helm 步骤

1. 添加 Open WebUI Helm 仓库：

   helm repo add open-webui https://open-webui.github.io/helm-charts
   helm repo update

2. 安装 Open WebUI Chart：

   helm install openwebui open-webui/open-webui

3. 验证安装：

   kubectl get pods

警告

如果您打算在集群化环境中使用多个节点/Pod/Worker 来扩展 Open WebUI 的规模，您需要配置一个 NoSQL 键值数据库（Redis）。 有一些环境变量必须为所有服务实例设置为相同的值，否则将会发生一致性问题、错误的 Session 会话以及其他问题！

重要提示： 默认的向量数据库 (ChromaDB) 使用的是本地 SQLite 支持的客户端，这对于多副本或多 Worker 部署是不安全的。SQLite 连接不是 fork 安全的，来自多个进程的并发写入会使 Uvicorn Worker 瞬间崩溃。您必须通过 VECTOR_DB 切换到外部向量数据库（PGVector, Milvus, Qdrant），或者通过 CHROMA_HTTP_HOST 将 ChromaDB 作为独立的 HTTP 服务器运行。

有关完整的步骤化扩展演练，请参阅 扩展 Open WebUI 规模。有关解决多副本问题的排错，请参阅 扩展与高可用指南。

升级时的关键注意事项

如果您运行的 Open WebUI 具有多个副本/Pod（replicaCount > 1）或 UVICORN_WORKERS > 1，您在升级期间必须缩减到单个副本/Pod。

1. 将 Deployment 缩容至 1 个副本。
2. 应用升级（拉取新的镜像版本）。
3. 等待 Pod 完全就绪（数据库迁移完成）。
4. 重新扩容至您期望的副本数量。

不遵守此规定可能会因并发的数据库迁移而导致数据库损坏。

访问 WebUI 界面

您可以通过端口转发（Port-forwarding）或配置 Ingress 来访问 Open WebUI。

Ingress 配置 (Nginx)

如果您使用的是 NGINX Ingress Controller，您可以启用会话亲和性（粘性会话，Sticky sessions）以提高 WebSocket 的稳定性。请将以下 Annotation 批注添加到您的 Ingress 资源中：

metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "open-webui-session"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

这可确保用户的 Session 会话保持连接到同一个 Pod，从而减少多副本配置中 WebSocket 连接的问题（当然，正确的 Redis 配置可以降低对此的依赖）。

卸载

1. 卸载 Helm Release：

   helm uninstall openwebui

2. 移除持久卷声明（警告：这会删除所有数据）： Helm 不会自动删除 PVC，以防止意外的数据丢失。如果您希望清除一切，必须手动删除它们。

   kubectl delete pvc -l app.kubernetes.io/instance=openwebui

Desktop 桌面版

桌面版 App

从 github.com/open-webui/desktop 下载桌面客户端。它无需 Docker 或手动安装，即可在您的系统上原生运行 Open WebUI。

信息

对于生产环境部署，请通过 Docker 或 Python 进行安装。

第三方

Pinokio.computer

Pinokio.computer 安装

若要通过 Pinokio.computer 安装，请访问其官网：

https://pinokio.computer/

关于此安装方法的支持由其官网提供。

---

安装之后

首次登录

• 管理员账户： 创建的首个账户将被授予管理员（Administrator）权限，并可控制用户管理和系统设置。
• 新账号注册： 随后的注册默认状态为待定（Pending），需要管理员批准后方可激活。
• 隐私性： 默认情况下，所有数据（包括登录信息）均本地存储在您的设备上。Open WebUI 默认不会发起外部请求。默认情况下所有模型均为私有的，必须显式设置为共享。

Connect a Model Provider

Open WebUI 需要至少连接一个模型提供商才能开始对话。请选择您的提供商：

提供商	指南
Ollama (本地模型)	Starting with Ollama →
OpenAI	Starting with OpenAI →
任何兼容 OpenAI 的 API	OpenAI-Compatible Providers →
Anthropic	Starting with Anthropic →
llama.cpp	Starting with llama.cpp →
vLLM	Starting with vLLM →

Connect an Agent

不仅想要交互模型？AI 智能体（Agent）可以通过 Open WebUI 熟悉的对话界面执行终端命令、读写文件、搜索网页、保留记忆并链式处理复杂的工作流。

智能体	描述	指南
Hermes Agent	由 Nous Research 提供的自主智能体，具有终端、文件操作、网页搜索、记忆和可扩展的技能	Set up Hermes Agent →
OpenClaw	开源自托管智能体，具有 Shell 访问、文件操作、网页浏览和即时通讯集成功能	Set up OpenClaw →

在 连接智能体（Agent）概述 → 中深入了解智能体与模型提供商的区别。

刚接触 Open WebUI？

如果这是您第一次接触 Open WebUI，请接下来阅读 Open WebUI 核心要素 指南。它涵盖了每个新用户都需要了解的六件事：插件（Plugins）、工具调用（Tool calling）、任务模型（Task models）、上下文管理、RAG 以及开放终端（Open Terminal）。

探索功能

连接成功后，探索 Open WebUI 的强大功能：功能概述 →

实验性功能：Open Responses

Open WebUI 对 Open Responses 规范具有实验性支持。请参阅 Starting with Open Responses Guide 指南了解更多。

---

社区

• Discord 进行提问、讨论和获取支持
• GitHub Issues 提交 Bug 报告和功能需求
• 想要贡献力量？ 测试 开发分支 并报告问题。无需编写代码。