> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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](/en/guide/guides/backup-restore.md) 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:

```bash
octop version
```

For a Docker deployment, check inside the container:

```bash
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](#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:


```bash Check only
octop update --check
```
```bash Install the stable release
octop update
```
```bash Skip the prompt
octop update --yes
```
```bash Include pre-releases
octop update --allow-prerelease --yes
```


The full option list is in [Server commands: octop update](/en/cli/server-commands.md#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`.


```bash macOS / Linux
curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash
```
```powershell Windows (PowerShell)
irm https://download.octop.cloud/octop/scripts/install.ps1 | iex
```
```bat Windows (cmd)
curl -fsSL https://download.octop.cloud/octop/scripts/install.bat -o install.bat
install.bat
```


## Upgrade a pip install

When Octop is installed in your own Python environment:

```bash
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](/en/guide/quickstart-docker.md).

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

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


**Docker Compose**

Run this in the directory that holds the Compose file. The China mirror file pulls `ghcr.nju.edu.cn/tencentcloud/octop:latest` and keeps the host mount at `~/.octop` (or `OCTOP_DATA`).
```bash
docker compose -f docker-compose.cn.yml pull
docker compose -f docker-compose.cn.yml up -d
```
When the file lives in the repo's `docker/` directory, change `-f` to `docker/docker-compose.cn.yml`.
For a source-built `docker-compose.yml`, rebuild and start from the repository root:
```bash
docker compose -f docker/docker-compose.yml up -d --build
```



> **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](https://github.com/TencentCloud/Octop/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](/en/guide/fnos.md).

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:

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


```bash System service
octop service restart
```
```bash Foreground process
octop run
```


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](#upgrade-a-source-checkout).
- Every mirror fails: retry on another network. A mirror can lag behind PyPI for a while.
