Upgrade Uptime Kuma 1.x to 2.0 as an in-place major-version migration: stop the existing service, make and verify multiple copies of the complete data directory, keep the same data mount, then start version 2 and watch its logs until the database migration finishes. Do not interrupt the migration. If it is interrupted, restore the backup and retry.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
The procedure differs slightly between Docker, Docker Compose and a PM2 installation. Uptime Kuma 2.0 also drops older Node.js releases, removes several legacy features and changes some defaults, so a successful container restart is not the end of the upgrade.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What changes when you move from Uptime Kuma 1.x to 2.0?
Uptime Kuma 2.0 is a major release with breaking changes. The official migration guide, edited by Louis Lam on April 28, 2026, specifically warns users to read the migration instructions before upgrading from version 1.
The migration rewrites the heartbeat table into a new optimized format. Its duration depends on the size of your database and the speed of the storage and host. The guide gives one real example—20 monitors with 90 days of data took about seven minutes—but it publishes no guaranteed time. A larger installation or slower hardware can take hours.
#1 Best Overall
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader
- CanaKit Premium High-Gloss Raspberry Pi 4 Case with Integrated Fan Mount, CanaKit Low Noise Bearing System Fan
- CanaKit 3.5A USB-C Raspberry Pi 4 Power Supply (US Plug) with Noise Filter, Set of Heat Sinks, Display Cable - 6 foot (Supports up to 4K60p)
- CanaKit USB-C PiSwitch (On/Off Power Switch for Raspberry Pi 4)
During this process, the application may appear inactive while the database is being transformed. Logs are the authoritative way to tell whether work is continuing. Stopping the process because the web interface is temporarily unavailable can leave the migration incomplete.
Preflight checklist before touching the installation
Complete these checks while version 1 is still running. They reduce the chance of a failed start and give you a practical rollback path.
Confirm the runtime and image constraints
- Docker: plan to use
louislam/uptime-kuma:2with the existing/app/datamount. Alpine-based images are no longer supported for this upgrade. - Rootless images: do not switch to a rootless image as part of the migration unless you have a separately tested recovery plan; the migration guide warns that rootless images are likely to encounter startup problems during a version 1-to-2 upgrade.
- Host operating system: Debian or Raspbian Buster systems should not be upgraded because of a documented
libseccomp2startup problem. - Non-Docker installations: Node.js 20.4 or newer is required. Support for Node.js 14, 16 and 18 has been dropped.
- Legacy browsers: older browsers are no longer supported by version 2, so plan to administer the new instance with a current browser.
Inventory integrations that may be affected
- Badge URLs that specify durations or feed them from scripts.
- SMTP subject and body templates.
- HTTP monitors that relied on the removed DNS Cache feature.
- Automation that assumes newly created monitors retry once by default.
- Any process that used Uptime Kuma’s old JSON Backup/Restore screen.
Schedule a maintenance window
Monitoring will be unavailable while the old service is stopped and while the database is migrated. Choose a window long enough for your data volume, and make sure you can access the host locally or through an out-of-band console if the web service does not return.
Back up the data directory and verify that it is restorable
The complete data directory is the supported backup unit in Uptime Kuma 2.0. The old JSON Backup/Restore feature has been removed, so exporting selected settings from the web interface is not a substitute for a filesystem copy.
- Stop Uptime Kuma cleanly using the method appropriate to your installation.
- Copy the entire data directory, including its database files and subdirectories, to separate storage.
- Make more than one copy. Keep at least one copy on a different disk or host; an external SSD or USB backup drive is optional storage, not an Uptime Kuma component.
- Record the source path, Docker volume name (if applicable), image tag, port mapping and ownership or permissions.
- Verify that the copies can be read and that their sizes are plausible. If your operational policy permits it, perform a test restore to a separate directory or host before the production upgrade.
Do not overwrite the only backup with a copy made after the migration starts. If the migration is interrupted, the official recovery instruction is to restore the pre-upgrade data directory and retry from the beginning.
Docker: upgrade an existing container
This procedure assumes the container is named uptime-kuma. Substitute your actual name, port and host directory or volume, but preserve the existing data mount exactly.
1. Stop the version 1 container
docker stop uptime-kumaStopping first prevents writes while you copy the database. If the command reports that the container is already stopped, continue only after confirming that no second Uptime Kuma process is using the same data.
2. Back up the mounted data
Copy the host directory or Docker volume that is mapped to /app/data. Do not back up only a single SQLite file: the supported recovery unit is the complete directory.
Rank #2
- Broadcom BCM2711, quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1. 5GHz
- 2. 4 GHz and 5. 0 GHz IEEE 802. 11b/g/n/ac wireless LAN, Bluetooth 5. 0, BLE
- 2 × USB 3. 0 ports, 2 x USB 2. 0 Ports
- 2 × micro HDMI ports supproting up to 4Kp60 video resolution
- Micro SD card slot for loading operating system and data storage
3. Change only the image tag
Keep the same port mapping, volume or bind mount, container name and other settings. Change the image to louislam/uptime-kuma:2. Do not combine the upgrade with a move to Alpine, a rootless image or a new data location.
4. Recreate the container
docker run -d --restart=unless-stopped -p <YOUR_PORT>:3001 -v <YOUR_DIR OR VOLUME>:/app/data --name uptime-kuma louislam/uptime-kuma:2Replace <YOUR_PORT> with the port you used before and <YOUR_DIR OR VOLUME> with the same bind mount or named volume. The important detail is that version 2 sees the existing version 1 data at /app/data; an empty mount creates what looks like a new installation.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems5. Follow the migration log
docker logs -f uptime-kumaLeave the command running until the migration messages finish and the application reports a normal startup. The heartbeat-table conversion can take substantially longer than the container’s image download. Do not press Ctrl+C in a way that stops the container, and do not remove or recreate the container while the migration is active. Exiting the log-follow command itself is harmless; stopping the application is not.
Docker Compose: upgrade a Compose stack
Compose users should change the service definition while retaining the existing volume declaration and mount target.
1. Stop the stack
docker compose downRun this from the directory containing your Compose file. Confirm that no separately managed Uptime Kuma container remains running.
2. Back up the data directory or volume
Use the same complete-directory backup procedure described above. If the Compose file uses a named volume, identify its host location or create an archive through a temporary helper container; do not replace the volume with a newly named one by accident.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 113. Change the service image
services:
uptime-kuma:
image: louislam/uptime-kuma:2Keep the existing volumes, ports, environment variables, restart policy and service name unless you have a separate reason to change them. In particular, keep the mount that places the old data at /app/data.
4. Start the updated service
docker compose up -dCompose will create a container from version 2 using the preserved data volume.
Rank #3
- Broadcom BCM2711, Quad core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5GHz
- 1GB, 2GB, 4GB or 8GB LPDDR4-3200 SDRAM (depending on model)
- 2.4 GHz and 5.0 GHz IEEE 802.11ac wireless, Bluetooth 5.0, BLE Gigabit Ethernet
- 2 USB 3.0 ports; 2 USB 2.0 ports.
- Raspberry Pi standard 40 pin GPIO header (fully backwards compatible with previous boards)
5. Watch all service logs
docker compose logs -fWait for the database conversion and normal application startup. If you operate several services, identify the Uptime Kuma service in the output and keep the stack running while its migration proceeds.
Non-Docker installation managed by PM2
A PM2 deployment needs a runtime check in addition to the data backup.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- Stop the process:
pm2 stop uptime-kuma. - Back up the complete Uptime Kuma
datadirectory and verify the copy. - Check the Node.js version:
node --versionThe result must be Node.js 20.4 or newer. Node.js 14, 16 and 18 are no longer supported by version 2. Upgrade the runtime before launching the new application, while keeping a record of the old installation and process configuration for rollback.
- Follow the project’s non-Docker update instructions to obtain and install the version 2 application files.
- Start the PM2 process with the same data directory and configuration used by version 1.
- Monitor the process logs continuously until the heartbeat migration completes.
If the process exits during migration, do not repeatedly restart it against the same partially migrated database. Stop it, restore the pre-upgrade data directory, correct the runtime or filesystem issue, and retry.
How to tell whether migration is progressing
Use the container or PM2 logs rather than the browser alone. A temporarily blank, unavailable or slow web interface is expected while the database is being transformed. Progress messages should continue to appear over time, although the interval between messages is not specified.
- Check that the process remains running and that log timestamps advance.
- Watch CPU, memory and disk activity on the host; sustained database activity can indicate normal work, but resource activity alone is not proof of success.
- Allow significantly more time than the seven-minute example if your history is larger or your storage is slower.
- Do not interrupt the process merely because the migration takes longer than your initial estimate.
When logs indicate completion, open the web interface, sign in, inspect several monitors and confirm that historical data and notification settings are present. Then test a notification channel and one representative public status page before declaring the maintenance complete.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Breaking changes to audit after the service returns
Badge duration syntax and limits
Version 2 accepts duration forms such as 24, 24h, 30d and 1y for badge endpoints. The documented limits are 720 hours, 1,440 minutes and 365 days. Review dashboards, README files, scripts and cached badge URLs that generate older duration syntax, and update them to a supported form within those limits.
SMTP LiquidJS variables are case-sensitive
SMTP subject and body templates now use case-sensitive LiquidJS variable names. The supported names are:
Rank #4
- Vilros Complete Starter Kit for Pi 4 Includes Raspberry Pi 4 Model B Board and all the accessories you need to get started.
- 9-PART KIT WILL HAVE YOU READY TO GET UP AND RUNNING: Kit Includes 1. Raspberry Pi 4 Model B Board 2. Case With Easy to connect Built-in fan 3. 64GB Micro SD card Preloaded with RP OS 4. Vilros Pi 4 Compatible Power Supply with Inline on/off switch (power supply color may vary white/black) 5. Micro HDMI to Standard HDMI cable (5ft) 6. Micro SD to USB adapter to reflash card if desired 7. Neoprene Storage Bag to store all parts when not in use 8. Set of 4 Heatsinks 9. Vilros QuickStart Guide instruction booklet for Pi 4
- PASSIVE & ACTIVE COOLING: The included case is well-vented and the kit also includes a set of heatsinks with thermal stickers for easy application and a pre-installed fan to keep the board cool in any use.
- CONVENIENT ACCESSORIES: The power supply features an inline on/off switch neoprene bag that holds and protects all the parts when not in use and the QuickStart guide is updated and written for Raspberry Pi 4.
- IMPORTANT: Kit does NOT include Keyboard, Mouse or Monitor
namemsgstatusheartbeatJSONmonitorJSONhostnameOrUrl
Audit every template for incorrect capitalization and variables that are no longer supported. Send a test notification after editing; a template can save successfully yet produce an incomplete message when a variable is misspelled.
New monitor retry default
Newly created monitors now default to zero retries instead of one. Existing monitor behavior should be checked against your intended alert policy, and provisioning scripts should set the retry value explicitly if they depend on a particular number.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Removed JSON Backup/Restore
Do not plan a post-upgrade recovery around the old JSON interface. Keep versioned copies of the complete data directory instead.
Removed DNS Cache for HTTP monitors
The DNS Cache feature for HTTP monitors has been removed. For Docker installations, the migration guide suggests using the bundled nscd approach where DNS caching is required. Recheck HTTP-monitor resolution behavior after the upgrade rather than assuming the old cache setting still applies.
Browser support
Legacy browsers are no longer supported. If the service is healthy but the administration interface fails to render, test with a current browser before changing the server.
Can you migrate SQLite to MariaDB at the same time?
Not as an officially supported part of the 1.x-to-2.0 upgrade. Uptime Kuma documents SQLite-to-MariaDB as a separate, third-party export/import project.
| Question | SQLite in-place upgrade | SQLite to MariaDB move |
|---|---|---|
| Officially supported path | Yes: upgrade version 1 on its existing database and let version 2 migrate it. | No direct, officially supported migration path is documented. |
| Tooling | Built into the version 2 startup migration. | Requires third-party export/import tooling and independent validation. |
| Known risk | Migration must not be interrupted; restore the complete backup if it fails. | The guide warns that sqlite3tomysql does not create all required indexes and can significantly reduce performance. |
| Relationship to the upgrade | This is the normal database path for an in-place upgrade. | Treat it as a separate project, not as a routine step in the version 1-to-2 upgrade. |
The safest sequence is to upgrade Uptime Kuma to version 2 on the existing SQLite database first. Only then consider a separately staged MariaDB migration that you have validated on a copy, with a tested rollback plan. A database conversion performed during the major-version migration makes it harder to determine whether a failure came from Uptime Kuma’s schema conversion or from the third-party import.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting a migration that appears stuck
The web page is unavailable but logs are active
Keep the service running and continue following the logs. Database size controls the duration, and the published seven-minute example is not a maximum. Check disk space and host resource usage without stopping the process.
Best Value
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- CanaKit 3.5A USB-C Power Supply with Noise Filter (UL Listed) specially designed for the Raspberry Pi 4 (5-foot cable)
- CanaKit USB-C PiSwitch (On/Off Power Switch)
- Set of 3 Aluminum Heat Sinks for the Raspberry Pi 4
No new log output and the process has exited
Capture the exit message, then stop any automatic restart loop. Do not launch version 2 repeatedly against the same data directory. Restore the untouched pre-upgrade backup, verify the Node.js version or Docker host constraints, and retry once the underlying issue is corrected.
Startup fails on Debian or Raspbian Buster
The documented libseccomp2 problem affects these hosts. Do not proceed with the upgrade on that operating-system release without a separately validated remediation or a different host.
The container starts with no monitors
Check the volume mapping first. Version 2 must mount the old directory or named volume at /app/data. A typo in the host path, a newly created volume or a changed Compose volume name makes the application see an empty data directory. Stop the container, restore the original mapping and use the backup if the migration already modified the wrong location.
Templates or badges stopped working
Inspect badge duration syntax and SMTP LiquidJS variable casing using the lists above. These are application-level breaking changes, not evidence that the database migration failed.
HTTP monitors behave differently
Review any dependency on DNS Cache, which was removed. For Docker, evaluate the suggested bundled nscd arrangement and retest the affected monitors.
Docker and non-Docker procedures compared
| Item | Docker | Docker Compose | Non-Docker with PM2 |
|---|---|---|---|
| Stop command | docker stop uptime-kuma |
docker compose down |
pm2 stop uptime-kuma |
| Runtime prerequisite | Supported non-Alpine image; avoid rootless image for this migration | Same image constraints as Docker | Node.js 20.4 or newer |
| Data preservation | Keep the existing directory or volume mounted at /app/data |
Keep the existing Compose volume and mount target | Keep the existing data directory |
| Start operation | Recreate with louislam/uptime-kuma:2 |
Change the image, then run docker compose up -d |
Install version 2 files and start the PM2 process |
| Log command | docker logs -f uptime-kuma |
docker compose logs -f |
Follow the PM2/application logs |
| Rollback | Stop version 2, restore the backed-up data mount and recreate the prior image | Restore the volume or directory, revert the image tag and run Compose again | Restore the data directory, reinstall the prior application files and restart PM2 |
Rollback principles
Rollback is a restore operation, not an image-tag flip alone. Once version 2 has begun rewriting the heartbeat table, the original database may no longer be in a state that version 1 can safely use. If you must abandon the upgrade:
Free tools Windows power users keep installed
One-click scans. No signup required.
- Stop the version 2 process.
- Preserve the logs and error message for diagnosis.
- Move the partially migrated data directory aside; do not overwrite your backup.
- Restore the complete pre-upgrade directory or volume copy.
- Revert the container image, Compose service or non-Docker application files to the version 1 setup.
- Start version 1 and confirm monitors, history and notifications before planning another attempt.
After correcting the cause—such as an unsupported Node.js release, an unsuitable host, an incorrect mount or insufficient storage—make a fresh verified copy and retry the migration from that clean version 1 state.
Post-upgrade validation checklist
- Version 2 starts without repeated crash loops.
- All expected monitors and their historical data are visible.
- At least one monitor records a new heartbeat.
- SMTP or other notification channels deliver a test message with correctly rendered variables.
- Badge URLs used by dashboards return data with supported durations.
- Public status pages and reverse-proxy routes still point to the same port and host.
- HTTP monitors that depended on DNS caching have been retested.
- Provisioning scripts set retry counts explicitly where zero-versus-one matters.
- The untouched pre-upgrade backup is retained according to your normal retention policy.
Bottom line
Upgrade in place, not by creating a fresh Uptime Kuma instance: stop the old service, preserve and verify the complete data directory, keep the existing mount, satisfy the runtime and host requirements, and monitor the migration logs without interruption. Handle SQLite-to-MariaDB separately, then audit badges, SMTP templates, DNS-cache dependencies, browser access and retry defaults before returning the monitor to normal operations.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
