Migrate from Umami to Muon

Muon is Umami-compatible — keep your existing tracker and bring your history.

How do I migrate from Umami to Muon?

Muon accepts Umami-compatible tracking payloads on the same /api/send endpoint, so you can point an existing Umami tracker at Muon and use the importer to bring historical data. No tracking code rewrite required.

Why it's easy

Same tracker shape, same endpoint.

Umami and Muon speak the same wire format. Muon exposes an Umami-compatible /api/send endpoint that accepts the exact payload your existing tracker already sends — the same event shape, the same website identifier, the same pageview and custom-event calls. Migration is mostly a matter of where the tracker points, not what it sends.

Umami-compatible endpoint. Events post to /api/send in the same format Umami uses.
No event rewrite. Your data-website-id maps to a Muon project; existing custom events keep working.
Bring your history. A best-effort importer reads your Umami PostgreSQL database directly.

Step 1

Stand up Muon.

Clone the repository and start the full stack — backend, dashboard, tracker and PostgreSQL — with Docker Compose.

Start Muon

# clone, enter, and bring the stack up
git clone https://github.com/runmuon/muon && cd muon && docker compose up -d

Once it's up, open the dashboard and create a project. You'll use that project's website id in the next step. For a production install, see the Kubernetes deployment guide.

Step 2

Point your tracker at Muon.

Swap the tracker src and host from your Umami instance to your Muon instance. The data-website-id maps to a Muon project — keep the rest of your events exactly as they are.

Repoint the tracking script

<!-- before: Umami -->
<script defer src="https://umami.example.com/script.js"
  data-website-id="a1b2c3d4-…"></script>

<!-- after: Muon (same website id, new host) -->
<script defer src="https://muon.example.com/script.js"
  data-website-id="a1b2c3d4-…"></script>

Only the host changes. Custom events keep firing to the Umami-compatible /api/send endpoint on your Muon instance — no changes to your event code.

Step 3

Import historical data.

Run the Umami importer against your existing Umami PostgreSQL database to bring your history across. The importer is best-effort — verify counts once it finishes.

Import from Umami Postgres

# point the importer at your existing Umami database
docker compose run --rm backend muon import umami \
  --source "postgres://user:pass@umami-db:5432/umami"

This is a best-effort import — spot-check pageview, session and event counts against your old Umami dashboard before you decommission it.

What transfers

What comes across, and what to watch.

The importer maps your Umami entities onto Muon's project and event model. Aggregates land close to your originals; derived metrics may shift slightly because Muon computes them server-side.

Websites → projects

Each Umami website becomes a Muon project, keyed on the same website id.

Pageviews

Historical pageviews import with their URL, referrer and timestamp.

Sessions

Imported, but session boundaries are re-derived server-side and may differ slightly.

Events (best-effort)

Custom events and their data import where the shape maps cleanly; verify after import.

Visitors

Visitor and session derivation differs server-side, so unique counts will be close, not identical.

Expect very close aggregates rather than an exact match — session and visitor derivation differs between the two systems.

After migrating

What you unlock on Muon.

Once your tracker points at Muon and your history is in, you get more than a faster Umami — you get change detection and investigation on top of the same data.

Findings. Muon detects meaningful changes with statistics first, then explains them in plain language. How Findings work →
Investigation. When a metric moves, Muon narrows it to the segment where it actually changed.
Browser health. Frontend failures, connected to product metrics — so you can see when a broken build costs conversions.

Weighing the move? See the full side-by-side in Muon vs Umami.

FAQ

Questions, answered directly.

Is Muon compatible with the Umami tracker?

Yes. Muon accepts Umami-compatible tracking payloads on the same /api/send endpoint, so an existing Umami tracker can send events to Muon without changes to your event code.

Do I have to change my tracking code?

No. Repoint the tracker host to your Muon instance and keep your existing events. The data-website-id maps to a Muon project, so no event rewrite is required.

Can I import my Umami history?

Yes. A best-effort importer reads your existing Umami PostgreSQL database and brings websites, pageviews, sessions and events into Muon. Verify counts after importing.

Will my numbers match exactly?

Expect close, not identical. Session and visitor derivation differs server-side, so aggregate numbers will be very close but may not match Umami exactly.

Is Muon faster than Umami?

In an internal benchmark on the same Umami-compatible /api/send endpoint and identical PostgreSQL setup, Muon showed materially higher throughput and lower latency. Read the methodology before making production decisions.

Umami-compatible · self-hosted

Move to Muon without a rewrite.

Stand up Muon, repoint your tracker, and import your history. Keep the events you have — gain findings and investigation.

Start with Docker → Muon vs Umami