# Updating ZoPanel

> Update ZoPanel from the panel or with zopanel update. Every update snapshots the database, checks health and rolls back by itself if needed.

Source: https://zopanel.net/docs/updating  
Updated: 2026-10-07

ZoPanel updates itself as one signed binary. Each update is guarded: the panel database is saved first, the new version must pass a health check, and if it does not, the previous version and its database come back automatically. This page covers manual and automatic updates, and how to roll back by hand.

## What an update does

1. **Download and verify.** The release manifest for your channel is downloaded and its Ed25519 signature checked. The binary must match the SHA-256 in that signed manifest. Unsigned or modified releases are refused.
2. **Keep the previous version.** The running binary is copied aside so it can be restored.
3. **Snapshot the database.** The panel database is copied consistently to `/var/lib/zopanel/pre-update/`. The last 3 snapshots are kept. If the snapshot fails, the update stops and the services are not restarted on the new version.
4. **Restart on the new version.** Both services, `zopanel-agent` and `zopanel`, restart. The new version migrates the database on start.
5. **Health check.** The guard waits up to 3 minutes for both services to be active, the agent to answer and the panel's health check to pass, then checks again after 20 seconds to make sure it stays up.
6. **Automatic rollback.** If the health check fails, the previous binary and the database snapshot are put back, and the services restart on the old version.

The guard runs as its own systemd unit, so a dropped SSH connection or closed browser tab does not stop it halfway. Your websites, databases and mail keep running throughout: only the panel and its agent restart.

## Update from the panel

1. Go to **Settings → Updates**.
2. The card shows the **Installed version** and **Latest version**. Click **Check now** to look again.
3. When a new version is available, its release notes are shown. Click **Update now**.

The update runs as a task. The panel is unavailable for a few moments while it restarts.

## Update from the command line

As root on the server:

```bash
zopanel update
```

It prints each step and ends with `ZoPanel X.Y.Z is up and healthy`, or with the reason it rolled back. If you are already on the latest version, it says so and does nothing.

To check the installed version:

```bash
zopanel version
```

## Automatic updates and channels

In **Settings → Updates → Update preferences**:

| Setting | Options | Effect |
| --- | --- | --- |
| **Channel** | Stable, Beta | Which releases the server installs |
| **Automatic updates** | On / off | Installs new releases at 04:00 server time |

Automatic updates are off until you turn them on. When they are off, the panel checks once a day and sends an **Update available** alert once per new release.

Automatic updates use the same guard as manual ones.

## Alerts about updates

In **Settings → Alerts**, turn on these events to be told about updates by Telegram, email or webhook:

- **Panel update failed or rolled back**: the new version did not become healthy and was rolled back, or the update failed.
- **Update available**: a new release is out (when automatic updates are off).

If the server restarts in the middle of the health check, the panel reports that the update was not checked, and you can decide whether to keep it or roll back.

## Roll back by hand

If a new version works but you prefer the previous one, run as root:

```bash
zopanel rollback
```

This puts the previous binary back and restarts the services. What happens to the panel database depends on the situation:

| Situation | Database |
| --- | --- |
| The last update failed less than 30 minutes ago | Restored from the snapshot taken before that update |
| The update succeeded, or the snapshot is older | **Kept as it is**, so changes made since (accounts, websites, mailboxes) are not lost |

The command prints which case applies and how old the snapshot is.

### `--db`: also restore the database

```bash
zopanel rollback --db
```

Also restores the database snapshot taken before the last update, whatever its age. Use it when the previous version cannot run on the current database. **Everything changed in the panel since that update is lost**: accounts, websites, databases, mailboxes and settings created or changed after it. Website files and the contents of customer databases are not part of the panel database, but the panel's records of them are.

### `--binary-only`: never touch the database

```bash
zopanel rollback --binary-only
```

Puts the previous binary back and always keeps the current database.

Rollback fails with `no previous version to roll back to` if no previous binary is saved, for example right after a fresh installation.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| The panel does not open after an update | Wait up to 3 minutes for the guard to finish. Then run `systemctl status zopanel zopanel-agent` and `journalctl -u zopanel`. |
| The update rolled back | The alert and the task log give the reason. Run `zopanel ctl doctor`, and send `zopanel ctl support-bundle` to support if needed. |
| Websites behave differently after an update | Run `zopanel ctl rebuild` to apply every account and website's configuration again. |

## Updating the operating system

ZoPanel updates do not upgrade your system packages. The installer turns on automatic security updates (unattended-upgrades). The **Security Center** on the **Security** page tells you when security updates are pending or a restart is needed after a kernel update.