# Upgrade a bench

Upgrading moves a bench to a newer release of PLESTY Bench, the application
itself. What the bench holds — its installed device and experiment modules,
fleets, device configuration, logs and runs — is untouched by it. To update a
module instead, see [Install and update modules](modules.md).

A bench is always exactly the release it installed: the installers pin the
version they were built for, never *latest*, so nothing changes under a
running bench until someone upgrades it.

## Knowing there is one

When a newer release is out, the status bar says so on start —
*Update available: plesty-bench 0.5.1* — and clicking it opens *Help ▸ Check
for updates…*. The console asks PyPI at most once a day, and says nothing
when there is no network. *Server ▸ Configure…* ▸ *Check for updates at start*
turns it off.

## Upgrade from the console

1. *Help ▸ Check for updates…* shows the version installed and the newest one
   on PyPI.
2. Press **Update**. It closes the app — asking first if servers or jobs are
   running, as closing always does — and opens the *Updating PLESTY Bench*
   window, which shows the install as it runs.
3. When it has finished, the window says how it went and offers **Open PLESTY
   Bench**, or **Close** to open it later.

If the install fails, the version you had stays in place and the window says
why. The details are in `%LOCALAPPDATA%\PLESTY Bench\update.log` on Windows
and `~/.local/state/plesty-bench/update.log` on macOS and Linux.

*Help ▸ About* keeps the details of the running version: how and where it is
installed, its Python, the last update — from which version to which, when,
how it went, with its log — and a link to what changed in this version.

## Upgrade by hand

On **macOS and Linux**, name the release:

```bash
uv tool install --force "plesty-server[gui]==0.5.0"
```

`uv tool upgrade plesty-server` does **not** move a bench the installer set
up: uv keeps the version the tool was installed with, and the installer
installed an exact one. It does upgrade an installation made by hand without a
version.

On **Windows** the application is not in uv's tool environment
([why](../design/packaging.md#where-the-application-lands-and-why-windows-differs)),
so by hand the upgrade goes through its own environment, with the app closed:

```powershell
& "$env:LOCALAPPDATA\PLESTY Bench\app\Scripts\python.exe" -m pip install --upgrade "plesty-server[gui]"
```

Running the newer release's `setup.exe` over the installed one upgrades it
too.

A copy run from a **source checkout** is not an install and offers no Update;
update the checkout itself (`git pull`, `uv sync`).

## The client on another machine

The client you drive benches with from your own machine upgrades on its own:

```bash
uv tool upgrade plesty-bench
```

Client and bench do not have to match — `describe` reports the bench's
version, and the client's own commands are stable — but a feature added on one
side needs the other. See [Work from another machine](remote.md).