docs-openwebui/docs/getting-started/updating.mdx

---
sidebar_position: 300
title: "Updating Open WebUI"
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Updating Open WebUI

**Stay current without losing your data.**

Your data (chats, users, settings, uploads) lives in a Docker volume or local database, not inside the container. Updating Open WebUI means swapping the container image for a newer one. Your data stays exactly where it is.

---

## Choose Your Update Strategy

Before running any commands, decide how you want to track releases. The right choice depends on how you use Open WebUI.

| Scenario | Recommended approach |
|---|---|
| **Personal / homelab** | Use the `:main` tag and pull manually when you want the latest |
| **Shared / team instance** | Pin a specific version (e.g. `:vX.Y.Z`) and use [Diun](#diun) for update notifications |
| **Production / critical** | Pin a version, review [release notes](https://github.com/open-webui/open-webui/releases) before upgrading, test in staging first |
| **Testing the next release** | Run the `:dev` pre-release on a second instance with its own volume, alongside whatever you run in production |

Whichever row you are in, a second instance on `:dev` is worth having, and adding one costs you a tag, a volume and a port. It shows you the next release before it reaches your users, it tells you whether your plugins and your configuration still work, and anything it turns up gets fixed before the release rather than after it.

### `:main` vs. Pinned Versions

The `:main` tag always points to the **latest build**. It's convenient but can include breaking changes without warning.

For stability, pin a specific release tag:

```
ghcr.io/open-webui/open-webui:vX.Y.Z
ghcr.io/open-webui/open-webui:vX.Y.Z-cuda
ghcr.io/open-webui/open-webui:vX.Y.Z-ollama
```

Browse all available tags on the [GitHub releases page](https://github.com/open-webui/open-webui/releases).

---

## Before You Update

1. **Back up your data** (see [Backup & Restore](#backup--restore) below). Especially important before releases with database migrations, which can be hard to undo.
2. **Check the [release notes](https://github.com/open-webui/open-webui/releases)** for breaking changes.
3. **Clear your browser cache** after updating (`Ctrl+F5` / `Cmd+Shift+R`) to avoid stale frontend assets.

:::info v0.11.4 hides the personal Integrations tab
Since v0.11.4, personal tool servers sit behind the **Direct Integrations** switch in the **User Connections** section of **Settings > Admin > Integrations** (or [`ENABLE_DIRECT_INTEGRATIONS`](/reference/env-configuration#enable_direct_integrations)), which starts off. Users who had the `direct_tool_servers` permission lose sight of the **Integrations** tab in their settings until you turn it on, admins included.
:::

:::info v0.12.1 adds sign-in records for SCIM users
This release runs a database migration that adds a sign-in record to every account that lacks one, in practice the accounts created through [SCIM](/features/authentication-access/auth/scim#integration-with-sso). It changes data only. Back up first. The added records carry no usable password, so these users keep signing in through SSO.
:::

:::warning Running multiple replicas?
Update every instance at the same time. Rolling updates are not supported across a release that changes the database schema: the migration moves the whole database forward at once, while the instances still on the old version keep querying the old shape. Stop all replicas, let one instance migrate, then bring the rest back up on the new version.

Setting `ENABLE_DB_MIGRATIONS=false` on all but one instance decides **which** instance runs the migration, it does not make a mixed-version fleet safe. See [Updates and Migrations](/troubleshooting/multi-replica#updates-and-migrations) for the full procedure and the [Scaling guide](/getting-started/advanced-topics/scaling) for the surrounding setup.
:::

---

## Manual Update

<Tabs groupId="setup-method">
  <TabItem value="docker-run" label="Docker Run" default>

```bash
# 1. Stop and remove the container (data in the volume is preserved)
docker rm -f open-webui

# 2. Pull the latest image (or replace :main with a pinned version)
docker pull ghcr.io/open-webui/open-webui:main

# 3. Recreate the container
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -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
```

For NVIDIA GPU support, add `--gpus all` to the `docker run` command.

  </TabItem>
  <TabItem value="docker-compose" label="Docker Compose">

```bash
docker compose pull
docker compose up -d
```

Make sure your `docker-compose.yml` includes `WEBUI_SECRET_KEY`:

```yaml title="docker-compose.yml"
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      - WEBUI_SECRET_KEY=your-secret-key
    restart: unless-stopped

volumes:
  open-webui:
```

  </TabItem>
  <TabItem value="python" label="Python (pip)">

```bash
pip install -U open-webui
```

The `-U` flag upgrades to the latest version. Then restart the server:

```bash
open-webui serve
```

  </TabItem>
</Tabs>

:::warning Set WEBUI_SECRET_KEY to avoid logout on every update
Without a persistent `WEBUI_SECRET_KEY`, a new key is generated each time the container is recreated, invalidating all sessions. Generate one with `openssl rand -hex 32` and keep it across updates. See the [Environment Variable Reference](/reference/env-configuration) for details.
:::

### Verify the Update

After updating, confirm everything is working:

1. **Check version in logs:**
   ```bash
   docker logs open-webui 2>&1 | head -20
   ```
2. **Load the UI** at [http://localhost:3000](http://localhost:3000). You should see the login page.
3. **If the UI looks broken**, clear your browser cache (`Ctrl+F5` / `Cmd+Shift+R`).
4. **If you see migration errors** in the logs, check the [release notes](https://github.com/open-webui/open-webui/releases) for known issues and the [Connection Errors](/troubleshooting/connection-error) troubleshooting page.

---

## Rolling Back

If an update causes problems, you can go back to a previous version by pinning its tag.

<Tabs groupId="setup-method">
  <TabItem value="docker-run" label="Docker Run" default>

```bash
docker rm -f open-webui
docker pull ghcr.io/open-webui/open-webui:v0.8.3
docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
  --add-host=host.docker.internal:host-gateway \
  -e WEBUI_SECRET_KEY="your-secret-key" \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:v0.8.3
```

  </TabItem>
  <TabItem value="docker-compose" label="Docker Compose">

Change the image tag in your `docker-compose.yml`:

```yaml
image: ghcr.io/open-webui/open-webui:v0.8.3
```

Then:

```bash
docker compose pull
docker compose up -d
```

  </TabItem>
  <TabItem value="python" label="Python (pip)">

```bash
pip install open-webui==0.8.3
open-webui serve
```

  </TabItem>
</Tabs>

:::caution Database migrations are one-way
If the version you updated to ran a database migration, rolling back the container **does not** undo the migration. The older version may not work with the newer database schema. In that case, you need to restore from a backup taken **before** the update. For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.
:::

---

## Stay Notified About Updates

Instead of checking manually, use a tool to monitor for new releases. Options are listed from safest to most hands-on.

:::tip Recommendation
- **Production / critical systems:** Diun (notification-only) + manual updates
- **Managed environments:** WUD (visual dashboard + manual trigger)
- **Homelabs / personal use:** Watchtower (fully automated)
:::

| Feature | Diun | WUD | Watchtower |
|---------|:---:|:---:|:---:|
| **Auto-updates containers** | ❌ | ❌ (manual via UI) | ✅ |
| **Web interface** | ❌ | ✅ | ❌ |
| **Notifications** | ✅ | ✅ | ✅ |
| **Docker 29+** | ✅ | ✅ | ✅ (forks) |
| **Resource usage** | Very Low | Medium | Low |

### Diun

Notification-only. Alerts you when updates are available (email, Slack, Discord, Telegram, etc.) without touching your containers. You decide when and how to update.

```yaml title="docker-compose.yml"
services:
  diun:
    image: crazymax/diun:latest
    container_name: diun
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data:/data
    environment:
      - TZ=America/New_York
      - LOG_LEVEL=info
      - DIUN_WATCH_WORKERS=10
      - DIUN_WATCH_SCHEDULE=0 */6 * * *  # Every 6 hours
      - DIUN_PROVIDERS_DOCKER=true
      - DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
      - DIUN_NOTIF_MAIL_PORT=587
      - DIUN_NOTIF_MAIL_USERNAME=your-email@gmail.com
      - DIUN_NOTIF_MAIL_PASSWORD=your-app-password
      - DIUN_NOTIF_MAIL_FROM=your-email@gmail.com
      - DIUN_NOTIF_MAIL_TO=your-email@gmail.com
    restart: unless-stopped
```

See [Diun documentation](https://crazymax.dev/diun/) for full setup and notification options.

### What's Up Docker (WUD)

Web UI for monitoring container updates and triggering them manually. See [WUD documentation](https://getwud.github.io/wud/) for setup.

### Watchtower

Fully automated. Pulls new images and recreates containers without intervention.

:::warning
The original `containrrr/watchtower` is **no longer maintained** and fails with Docker 29+. Use the [nicholas-fedor/watchtower](https://watchtower.nickfedor.com/) fork instead.
:::

:::warning
Automated updates can break your deployment if a release includes breaking changes or database migrations. Review release notes before auto-updating production systems, and always have a backup.
:::

**One-time update:**
```bash
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --run-once open-webui
```

**Continuous (check every 6 hours):**
```bash
docker run -d --name watchtower --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --interval 21600 open-webui
```

Set `WATCHTOWER_CLEANUP=true` to auto-remove old images. See [Watchtower docs](https://watchtower.nickfedor.com/) for scheduling, notifications, and monitor-only mode.

---

## Backup & Restore

All data lives in the `open-webui` Docker volume, including:
- **Database**: chats, users, settings, admin configuration
- **Uploaded files**: documents, images, knowledge base content
- **Generated content**: image generation outputs, exported data

### Backup

```bash
docker run --rm -v open-webui:/data -v $(pwd):/backup \
  alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz /data
```

Back up **before every update** and on a regular schedule (daily or weekly, depending on how actively you use Open WebUI).

### Restore

:::caution
The restore command **deletes everything in the volume** before extracting the backup. Make sure you're restoring the right file.
:::

```bash
docker stop open-webui
docker run --rm -v open-webui:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-YYYYMMDD.tar.gz -C /"
docker start open-webui
```

Replace `YYYYMMDD` with the actual date of your backup file.

For database-specific recovery, see the [Manual Database Migration](/troubleshooting/manual-database-migration) guide.

---

## Related Guides

- [Scaling Open WebUI](/getting-started/advanced-topics/scaling): multi-replica deployments
- [Connection Errors](/troubleshooting/connection-error): troubleshooting post-update connectivity issues
- [Environment Variable Reference](/reference/env-configuration): all configuration options including `WEBUI_SECRET_KEY`
- [Release Notes](https://github.com/open-webui/open-webui/releases): changelog for every version