How to Update Uptime Kuma on xCloud
Updated November 3, 2026 · 5 min read
You update Uptime Kuma on xCloud in one of two ways, depending on how your site was installed. New sites run in Docker, and you update them from the dashboard. Older sites run on PM2, and you update them with commands. xCloud does not update either kind automatically. New to it? See Uptime Kuma hosting on xCloud for what the one-click install sets up.
Check which kind of site you have
Open your site in xCloud and look at the top of the page.
| What you see | Your site runs on | Follow |
|---|---|---|
| An App Actions button, and a Docker Container Health table on Site Overview | Docker | Update a Docker site |
| No App Actions button | PM2 | Update an older PM2 site |
Update a Docker site
The version is set on one line in your site’s Environment page, and the Image column in Step 1 shows the version your site runs now. As of November 2026, the newest Uptime Kuma release is 2.5.9. Check the Uptime Kuma releases page for the version you want.
Step 1: Check your current version
Go to Site Overview and find Docker Container Health. The Image column shows the version you run now.
Step 2: Back up the site
Go to Backup → Previous Backups and click Backup Now. Wait until the new row shows Completed. The app stops for a moment while the backup runs. For schedules and restores, see backup and restore Docker apps.
Step 3: Change the version and redeploy
Go to Environment and find the UPTIME_KUMA_IMAGE line.
Replace everything after the = with the new version. Remove the @sha256: part as well, because it locks the line to the old version:
UPTIME_KUMA_IMAGE=louislam/uptime-kuma:2.5.9Click Save & Redeploy. xCloud downloads the new version and restarts the app, so your dashboard is unavailable for a short time.
Step 4: Confirm the update
Open your site and sign in. Then open the profile menu at the top right of Uptime Kuma and go to Settings → About, which shows the running version. The Image column on Site Overview updates on its own schedule, so it can show the old version for a few minutes.
If the new version misbehaves, restore the backup from Step 2. A new version can change your stored data, so setting the old version back without restoring is not a safe undo.
When to use App Actions → Update
App Actions → Update downloads the version named on the UPTIME_KUMA_IMAGE line and recreates the app. Your data is kept. While that line names a fixed version, such as 2.5.7, you stay on that version.
xCloud asks you to confirm before it starts:
To have Update pick up new releases, set the line to the 2 tag that Uptime Kuma publishes for its newest 2.x version:
UPTIME_KUMA_IMAGE=louislam/uptime-kuma:2After that, each Update moves you to the newest 2.x release. It never moves you to a new major version.
Update an older PM2 site
Use these steps only if your site has no App Actions button. Don’t run git pull origin master. It usually stops with an error about local changes. If it does run, it moves you to the code on master, which as of November 2026 is the Uptime Kuma 3.0 beta and needs Node.js 26.2 or newer.
Step 1: Check Node.js and back up
Uptime Kuma 2.5.9 needs Node.js 20.4 or newer. Your server may run an older version. To check, open your server, go to Management → Node Configuration and look at Default Server Node.js Version.
If it shows a version below 22, change the Node.js version to Node.js 24, or 22 if your app needs it, before you continue. Node.js 20 and older no longer get security fixes. The version applies to every Node.js site on the server, so check your other Node.js sites as well.
Then back up the site, because your monitors live in its database. Go to Backup → Previous Backups, open the Local Backup tab and click Backup Now. If xCloud asks which type you want, choose Full Backup and click Backup. Wait until the new row shows the size of your files and your database. A row with a Retry button failed, so get a good backup before you continue. For remote storage and schedules, see site backups.
The Backup menu needs a paid plan. If it is locked, upgrade before you update, because you have no way back without a backup.
If you are still on Uptime Kuma 1.x, read the v1 to v2 migration guide before you continue. That update changes your stored data and can take hours on a large site. Don’t interrupt it.
Step 2: Connect over SSH
Go to Access Data → SSH/sFTP on your site. It shows your Site Username and the SSH String to connect with. If you have not added a key yet, read how to add SSH keys. Connect as the site user.
Use SSH, not Tools → Commands. Commands stops a command after 10 minutes, and the npm steps below may not finish in that time, which can leave your site half updated. Commands also needs two-factor authentication on your account.
Step 3: Run the update
In your SSH session, run these lines. Replace example.com with your site’s domain, and 2.5.9 with the version you want. Use a numbered release, not master:
cd /var/www/example.com
cp ecosystem.config.js ~/ecosystem.config.js.xcloud
git fetch --all --tags
git checkout 2.5.9 --force
npm install --omit dev --no-audit
npm run download-dist
cp ~/ecosystem.config.js.xcloud ecosystem.config.js
pm2 restart ecosystem.config.js --update-env
pm2 saveThe cp lines matter. xCloud keeps your site’s name, port and database settings in ecosystem.config.js. The git checkout --force line replaces that file with Uptime Kuma’s default, so the commands save your copy first and put it back afterwards.
Step 4: Confirm the update
Open your site and sign in. Then open the profile menu at the top right of Uptime Kuma and go to Settings → About to see the running version.
If the site doesn’t come back, go to Settings → Rescue Site, turn on Repair PM2 Process & ecosystem.config.js, and click Run Now. xCloud writes ecosystem.config.js again from your site’s settings and starts the app.
If it still fails, restore your backup. Go to Backup → Previous Backups, open the Local Backup tab, open the menu on the row of the backup from Step 1 and click Restore Backup.
Frequently asked questions
Does xCloud update Uptime Kuma automatically?
No. A new site installs the version xCloud offers at that time, and an existing site stays on its version until you update it.
Why did App Actions → Update not change my Uptime Kuma version?
Update downloads the version named on the UPTIME_KUMA_IMAGE line in Environment. A new site names one fixed version there, so Update reinstalls that same version. Change the line to move to a newer one.
Will updating delete my monitors?
No. On a Docker site your data stays in its data volume when the app restarts, and on a PM2 site your database stays in place. Back up first anyway, because a new version can change how your data is stored.
Why does git pull fail on my PM2 site?
xCloud and npm change two files that Uptime Kuma also keeps in its code, so git refuses to overwrite them. Follow the PM2 steps on this page, which keep your settings and move to a stable release.
Related guides
- Deploy Uptime Kuma with xCloud
- Reset your Uptime Kuma password (older PM2 sites only)
If you run into any issues while updating Uptime Kuma, feel free to reach out to our support team.