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.

Updated Oct 7, 2026 · 4 min read

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:

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:

zopanel version

Automatic updates and channels

In Settings → Updates → Update preferences:

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:

zopanel rollback

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

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

--db: also restore the database

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

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

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.