Skip to content

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

Before You Start

Stop Uptime Kuma first.

  • Back up the whole data directory. Include kuma.db and db-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.

Breaking Changes

  • Prometheus: /metrics is disabled by default (Due to the CPU usage). Enable it in Settings β†’ General β†’ Prometheus API.
  • linux/arm/v7 is 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. Plain node server/server.js no longer works.
  • (Non-Docker) PM2 users should use pm2 start instead of pm2 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.

Docker Tags

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

Migration Steps (Docker)

  1. Stop the container.
docker stop uptime-kuma
  1. Back up the data directory.
  2. 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
  1. Watch the logs.
docker logs -f uptime-kuma
  1. Open the web UI and log in.

Migration Steps (Docker Compose)

  1. Stop the stack.
docker compose down
  1. Back up the data directory.
  2. Change the image tag to louislam/uptime-kuma:beta.
services:
    uptime-kuma:
        image: louislam/uptime-kuma:beta
....
  1. Start the stack.
docker compose up -d
  1. Watch the logs.
docker compose logs -f
  1. Open the web UI and log in.

Migration Steps (Non-Docker / PM2)

  1. Stop Uptime Kuma.
pm2 stop uptime-kuma
  1. Back up the data directory.
  2. Check Node.js. Version 26.2.0 or newer is required.
node --version
  1. Update the source to the beta tag.
git fetch --all --tags
git checkout 3.0.0-beta.1 --force
  1. Install dependencies and the prebuilt frontend.
npm install --omit dev --no-audit
npm run download-dist
  1. Remove the existing process first.
pm2 delete uptime-kuma
  1. The old pm2 start server/server.js no longer works. Start it with this:
pm2 start
pm2 save
  1. Open the web UI and log in.

FAQ

Can I upgrade directly from v1 to v3?

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.

Can I downgrade to v2/v1?

No. The database is upgraded in place. Restore the backup you made before upgrading.

Which Docker tag should I use?

Use louislam/uptime-kuma:beta during the beta.

What should I do, if I am using a armv7 device?

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

Clone this wiki locally