How to upgrade Octop
An upgrade replaces the Octop program. Accounts, experts, chats and memory, skills, channels, and model settings stay in the working directory. That directory is ~/.octop by default, or the path in OCTOP_HOME.
Back up before you upgrade. The new version loads after a restart. A restart pauses conversations that are in progress.
The web UI and octop update install a version that is newer than the one you are running.
Check the current version
Open Admin → Application Settings → App Updates and read Current Version.
You can also run this on the machine that hosts Octop:
For a Docker deployment, check inside the container:
Upgrade in the web UI
App Updates is for an administrator who has the update permission. Open Admin → Application Settings, then select App Updates.
Check for updates
Stable releases only is on by default. Automatic checks report stable releases. To install an alpha, beta, rc, or dev build, turn the switch off, then click Check for Updates.
Install the new version
When you see New version available, click Upgrade Now. Octop asks you to confirm again when the target is a pre-release. The page shows download and install progress, and Release Notes when the release includes them.
Restart
Restart Octop after the upgrade finishes. When Octop runs as a system service, click Restart Service. The page refreshes after about 1–2 minutes. When you started Octop with octop run in the foreground, stop that process and run octop run again, or run octop service restart. A desktop install restarts itself after a successful upgrade.
An editable install from Git asks you to use git pull. Follow Upgrade a source checkout below.
Version info sometimes comes from a mirror and can lag behind PyPI. When the update server is unreachable, check your network and click Check for Updates again, or run octop update --verbose.
Octop on a Tencent Cloud Lighthouse or CVM instance uses this same page. You can also sign in to the instance and run the commands below.
Upgrade with the CLI
When the install script or a managed virtual environment has put octop on your PATH, run:
The full option list is in Server commands: octop update.
Re-run the install script
When you installed Octop with the official script, run that same command again. The script reuses the environment and data under ~/.octop.
Upgrade a pip install
When Octop is installed in your own Python environment:
When you installed optional extras such as browser automation, keep the same extra, for example pip install -U "octop[browser]".
Upgrade Docker
The image already contains Octop. Pull a new image and recreate the container. Keep the same data volume. :latest is the lite image. Pull :full or :<version>-full when the container needs a virtual desktop, OCR, or local embedding. Startup flags are in Docker setup.
If this install still has a segmented history archive (history_v2.sqlite), stop the old server before you upgrade. On startup, Octop moves those messages back into the original history tables and renames the archive with a .migrated-<timestamp> suffix. OCTOP_HISTORY_V2_ENABLED is ignored.
The example uses the China mirror. When you originally used the GitHub registry, change the image to ghcr.io/tencentcloud/octop:latest. Keep the same -v as the existing container. The named volume below is octop-data. When you mounted a host directory, keep that directory.
docker rm removes the container. Your data lives in the named volume or the host directory. Keep that volume and directory. Skip docker volume rm during an upgrade.
Upgrade on FnOS
Download the new .fpk from GitHub Releases and install it again in App Center. The data directory and configuration stay in place. Package names and ports for the Docker and native editions are in FnOS.
On the native edition you can also click Upgrade Now in the web UI, or run octop update on the NAS. When octop is not on your PATH, use /usr/local/bin/octop or /var/apps/octop-native/bin/octop-cli. The upgrade writes into the App Center package directory. Restart Octop in App Center when it finishes.
Upgrade a source checkout
Update an editable install from the repository directory. Pull the latest code, build the web UI, then install into the current environment:
You can also run npm ci && npm run build inside dashboard. That matches make build-frontend.
Restart and confirm
Restart the process after the package update so Octop loads the new version.
Then run octop version, or return to App Updates and check Current Version.
When an upgrade fails
- The page says it cannot reach PyPI: check the host network or proxy, then click Check for Updates again. Add
--verboseon the CLI to print installer output. - The page reports a development install: follow Upgrade a source checkout.
- Every mirror fails: retry on another network. A mirror can lag behind PyPI for a while.

