Skip to main content

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.

ScenarioRecommended approach
Personal / homelabUse the :main tag and pull manually when you want the latest
Shared / team instancePin a specific version (e.g. :vX.Y.Z) and use Diun for update notifications
Production / criticalPin a version, review release notes before upgrading, test in staging first
Testing the next releaseRun 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.

Before You Update​

  1. Back up your data (see Backup & Restore below). Especially important before releases with database migrations, which can be hard to undo.
  2. Check the release notes for breaking changes.
  3. Clear your browser cache after updating (Ctrl+F5 / Cmd+Shift+R) to avoid stale frontend assets.
Running multiple workers or 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 and workers, let one instance migrate, then bring the rest back up on the new version.

Setting UVICORN_WORKERS=1 or 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 for the full procedure and the Scaling guide for the surrounding setup.

Manual Update​

# 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.

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 for details.

Verify the Update​

After updating, confirm everything is working:

  1. Check version in logs: 
    docker logs open-webui 2>&1 | head -20
  2. Load the UI at 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 for known issues and the Connection Errors troubleshooting page.

Rolling Back​

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

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
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 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.

Recommendation
  • Production / critical systems: Diun (notification-only) + manual updates
  • Managed environments: WUD (visual dashboard + manual trigger)
  • Homelabs / personal use: Watchtower (fully automated)
FeatureDiunWUDWatchtower
Auto-updates containers❌❌ (manual via UI)✅
Web interface❌✅❌
Notifications✅✅✅
Docker 29+✅✅✅ (forks)
Resource usageVery LowMediumLow

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.

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
      - [email protected]
      - DIUN_NOTIF_MAIL_PASSWORD=your-app-password
      - [email protected]
      - [email protected]
    restart: unless-stopped

See Diun documentation for full setup and notification options.

What's Up Docker (WUD)​

Web UI for monitoring container updates and triggering them manually. See WUD documentation 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 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:

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

Continuous (check every 6 hours):

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 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​

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.

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 guide.

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.