The container image and the saved conversations have different lifetimes in Open WebUI. A Docker update replaces the application image while the existing data mount keeps accounts, chats, and uploaded files available.
A single-container deployment also depends on its startup configuration. Environment variables, the original secret key, extra mounts, network membership, host mappings, port bindings, and restart policy must survive container replacement. A Compose-managed deployment belongs in How to run Open WebUI with Docker Compose instead.
An update can migrate the database, so the old image alone is not a recovery point. A tested pre-update backup and its matching secret configuration are needed before replacement. Custom Python tools or Functions also need compatibility review when a release changes the image's Python version.
Steps to update Open WebUI in Docker:
- Restrict newly created upgrade files to the current user.
$ umask 077
The saved container definition can contain passwords, API keys, and integration credentials. It belongs in protected local storage, outside shared folders and support tickets.
- Create a protected directory for the current deployment records.
$ mkdir -m 700 open-webui-upgrade
- Save the existing container definition without printing it.
$ docker inspect open-webui > open-webui-upgrade/container.json
The container name is open-webui here. The record identifies its actual storage, environment, listener, network, host mappings, restart policy, and custom settings.
- Retain the current image ID for recovery.
$ docker inspect --format '{{.Image}}' open-webui > open-webui-upgrade/old-image.txt
The local image ID identifies the original image even if its tag later moves. It must remain cached until the update is accepted.
- Record the running application's version.
$ curl -fsS http://127.0.0.1:3000/api/version > open-webui-upgrade/old-version.json
The address must match the existing port binding. The tested source release was 0.11.4.
- Prepare a replacement launch script from the original deployment configuration.
- open-webui-upgrade/recreate.sh
#!/bin/sh set -eu docker run --detach \ --name open-webui \ --publish 127.0.0.1:3000:8080 \ --env-file open-webui.env \ --mount type=volume,source=open-webui,target=/app/backend/data \ --add-host=host.docker.internal:host-gateway \ --restart unless-stopped \ "$1"
This definition fits an existing loopback-bound deployment with the open-webui volume and open-webui.env file. Any different binding, bind-mounted data, extra environment, mount, network, alias, command, or resource option belongs in the script with its original value. The image argument is the only intended change. The host mapping preserves access to host model servers on Linux Docker Engine; Docker Desktop already provides that hostname.
The env file must retain the active WEBUI_SECRET_KEY and every original environment override. A default generated key lives outside the usual data volume.
/app/backend/.webui_secret_key
An instance without its original key securely retained is not ready for replacement. A new key can break sessions and encrypted integration credentials.
- Compare the replacement script with the protected container definition.
The comparison covers all operator-supplied settings, including extra mounts, networks, aliases, host mappings, listener address, restart policy, and secret source. container.json is a reference record, not an executable restore command. A baseline command that omits an existing setting is not ready to run.
- Select the reviewed target image by version and digest.
$ target='ghcr.io/open-webui/open-webui:v0.12.4@sha256:a5b9e403d19154796850679c8c5d1295301cee954be8b84ddd62af92426558f7'
The tested upgrade was v0.11.4 to v0.12.4. The target release notes describe the move to Python 3.12 and Debian 13, which can affect custom dependencies.
- Pull the target image while the current container remains available.
$ docker pull "$target"
Downloading before the stop window avoids an outage while image layers transfer.
- Suspend user activity from the final backup until the update checks finish.
A scheduled maintenance window or existing ingress access controls can keep other clients from writing between backup and replacement.
- Complete a restore rehearsal of the existing data using How to back up and restore Open WebUI data.
The backup must include the whole data mount and matching original secret configuration. The rehearsal must recover an existing login, recognizable chat, and original upload bytes using the old image. External databases and object stores require coordinated backups. User writes must remain disabled from the final backup until the update checks finish.
- Stop the original container for replacement.
The service is unavailable during replacement and startup. The stopped container and pre-update backup remain available for recovery if startup fails.
$ docker stop open-webui open-webui
- Rename the stopped container to retain its original definition.
$ docker rename open-webui open-webui-previousThe name open-webui-previous must be unused. Renaming preserves the stopped container without deleting its volume. The two containers must never run against the same data volume simultaneously.
- Start the replacement from the reviewed launch script.
If the new release fails after opening the database, recovery may require the matching pre-update backup in a fresh volume with the original image and secret configuration. Starting the old container against migrated data can make recovery worse. How to back up and restore Open WebUI data covers restoration; image rollback alone does not restore data.
$ sh open-webui-upgrade/recreate.sh "$target"
- Check the replacement application's health endpoint.
$ curl -fsS http://127.0.0.1:3000/health {"status":true}
Startup can take several minutes. A failed request or any response other than {"status":true} requires investigation before user traffic returns.
Related: How to view Open WebUI Docker logs - Confirm that the application reports the target version.
$ curl -fsS http://127.0.0.1:3000/api/version {"version":"0.12.4","deployment_id":""}
The value must match the selected release and differ from the saved source version for this upgrade.
- Open http://127.0.0.1:3000 in a separate private browser window.

- Enter the existing account's email address in Email.

- Enter the account's password in Password.

- Click Sign in.

- Confirm that the existing account reaches its chat workspace.

- Open the chat sidebar.

- Open a recognizable conversation saved before the update.
The saved message text must match the original conversation.
- Open the pre-update upload attached to that conversation.
The preview shows extracted text when processing completed. No content alone does not establish whether the original file survived.
- Open the original file through its filename link in the preview.

- Download the original file by appending ?attachment=true to its address.

- Compare the downloaded file's SHA-256 hash with the original copy.
$ shasum -a 256 support-note.txt ~/Downloads/support-note.txt 9b10f0285d645babcde544fd3a00e5b125ecfaf1bfd2d5ef407a31fa844b8401 support-note.txt 9b10f0285d645babcde544fd3a00e5b125ecfaf1bfd2d5ef407a31fa844b8401 /Users/user/Downloads/support-note.txt
The hashes must match. The download path follows the browser settings. Matching hashes confirm that the original upload survived the update. The protected backup and stopped previous container remain available until normal use has been confirmed.