For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/guides/upgrade.md.
  • English
  • 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:

    octop version

    For a Docker deployment, check inside the container:

    docker exec octop octop version

    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.

    NOTE

    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:

    Check only
    Install the stable release
    Skip the prompt
    Include pre-releases
    Check only
    octop update --check

    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.

    macOS / Linux
    Windows (PowerShell)
    Windows (cmd)
    macOS / Linux
    curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash

    Upgrade a pip install

    When Octop is installed in your own Python environment:

    pip install -U octop

    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.

    docker run
    Docker Compose

    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 pull ghcr.nju.edu.cn/tencentcloud/octop:latest
    docker stop octop
    docker rm octop
    docker run -d \
      --name octop \
      -p 8088:8088 \
      -v octop-data:/data/.octop \
      -e HOME=/data \
      ghcr.nju.edu.cn/tencentcloud/octop:latest
    WARNING

    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:

    git pull
    make build-frontend
    pip install -e .

    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.

    System service
    Foreground process
    System service
    octop service restart

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