Repository navigation
Migration From v2 To v3
github-actions[bot] edited this page Nov 17, 2026
·
8 revisions
Warning
3.0.0-beta.1 is a beta release.
This is a major version update. It has breaking changes. Read this guide first.
Note
Stop Uptime Kuma first.
- Back up the whole
datadirectory. Includekuma.dbanddb-config.json. - Test that the backup restores.
- Keep another copy.
v3 upgrades the database in place. There is no downgrade path. The backup is the only way back.
- Prometheus:
/metricsis disabled by default (Due to the CPU usage). Enable it in Settings β General β Prometheus API. -
linux/arm/v7is no longer supported since Node.js 24. If you are running Uptime Kuma on armv7 devices like Raspberry Pi 2 or older, you should not update to v3. - (Non-Docker) Node.js 26.2.0 or newer is required.
- (Non-Docker) Start with
node --run start. Plainnode server/server.jsno longer works. - (Non-Docker) PM2 users should use
pm2 startinstead ofpm2 start server/server.js. - Migrated to Better Auth, it won't affect for normal users. However, if you used any 3rd party apps, it will probably be broken, due to the new auth method.
v3 has its own beta tags. They are separate from the v2 tags.
| Tag | Description |
|---|---|
beta |
Latest v3 beta (recommended for testing) |
beta-slim |
(Slim) Latest v3 beta |
beta-rootless |
Latest v3 beta (Rootless) |
beta-slim-rootless |
(Slim) Latest v3 beta (Rootless) |
nightly |
Daily build |
- Stop the container.
docker stop uptime-kuma- Back up the
datadirectory. - Change the image tag to
louislam/uptime-kuma:beta.
docker run -d --restart=unless-stopped -p <YOUR_PORT>:3001 -v <YOUR_DIR OR VOLUME>:/app/data --name uptime-kuma louislam/uptime-kuma:beta- Watch the logs.
docker logs -f uptime-kuma- Open the web UI and log in.
- Stop the stack.
docker compose down- Back up the
datadirectory. - Change the image tag to
louislam/uptime-kuma:beta.
services:
uptime-kuma:
image: louislam/uptime-kuma:beta
....- Start the stack.
docker compose up -d- Watch the logs.
docker compose logs -f- Open the web UI and log in.
- Stop Uptime Kuma.
pm2 stop uptime-kuma- Back up the
datadirectory. - Check Node.js. Version 26.2.0 or newer is required.
node --version- Update the source to the beta tag.
git fetch --all --tags
git checkout 3.0.0-beta.1 --force- Install dependencies and the prebuilt frontend.
npm install --omit dev --no-audit
npm run download-dist- Remove the existing process first.
pm2 delete uptime-kuma- The old
pm2 start server/server.jsno longer works. Start it with this:
pm2 start
pm2 save- Open the web UI and log in.
Yes, you can.
Of course, back up the data directory first.
Also, be sure you have read https://github.com/louislam/uptime-kuma/wiki/Migration-From-v1-To-v2.
No. The database is upgraded in place. Restore the backup you made before upgrading.
Use louislam/uptime-kuma:beta during the beta.
linux/arm/v7 is no longer supported since Node.js 24. Unfortunately, there are not many choices:
- Stay on v2
- Move to a 64-bit OS
- π§ How to Install
- π How to Update
- Environment Variables
- Docker Tags
- Migration from v1 to v2
- (Beta) Migration from v2 to v3
- Reset Password via CLI
- Status Page
- Notification Methods
- Badge
- How to Monitor Docker Containers
- Maintenance
- 3rd Party Addons/Apps
- Prometheus API Keys