TL;DR
A site operator moved a decade of analytics from a self-hosted Matomo instance to Umami by building a custom migration tool. The Python program reads Matomo (MariaDB/MySQL) data, generates SQL compatible with Umami (PostgreSQL), and the author validated the results with local imports before switching off Matomo.
What happened
The author decided to replace a long-running Matomo installation with Umami, citing Umami’s simpler hosting model and cleaner UI compared with Matomo’s older interface and broader feature set. Because there was no ready-made open-source importer, the author studied the two platforms’ schemas and implemented a custom Python migration tool (available as angristan/matomo-to-umami on GitHub). The tool extracts visitor sessions and pageview events from Matomo’s database and emits PostgreSQL INSERT statements matching Umami’s schema; the author intentionally avoided HTTP APIs to keep full control and speed up the transfer. A local docker-compose test environment was used to import and validate the generated dump. After a dry run that reported about 1.35 million sessions and roughly 2.0 million events across two sites, the SQL file was loaded into the Umami database and Matomo was decommissioned.
Why it matters
- Preserves historical analytics when switching platforms rather than losing years of data.
- Offers an open-source option for migrations where no official OSS importer exists.
- Demonstrates a practical path from MySQL/MariaDB-backed Matomo to PostgreSQL-backed Umami.
- Encourages verification via local dry runs to catch mapping or data issues before final import.
Key facts
- The migration tool is published as angristan/matomo-to-umami on GitHub and is written in Python.
- It reads Matomo’s database (MySQL/MariaDB) and generates SQL compatible with Umami’s PostgreSQL schema.
- The tool extracts visitor sessions and pageview events and maps fields like browser, country, outlinks, downloads, and return visits.
- A dry-run reported 1,352,812 total sessions and 1,999,709 total events to migrate.
- Per-site dry-run totals: angristan.fr — 861,301 sessions and 1,332,275 events; stanislas.blog — 491,511 sessions and 667,434 events.
- The dry-run reported an actual date range from 2015-01-18 to 2022-07-09, though the CLI was invoked with –start-date 2015-01-01 and –end-date 2022-07-10.
- Both Matomo and Umami were hosted on the author’s Kubernetes node; Matomo used MariaDB, Umami used PostgreSQL.
- Import into Umami’s database was performed by piping the generated migration.sql into psql inside the Umami pod (kubectl exec … env PGPASSWORD=<password> psql … < migration.sql).
What to watch next
- Run a local import and compare metrics before committing to a final migration — the author used a docker-compose test environment for validation.
- Matomo Cloud reportedly offers an import feature, but that implementation is not open source (the author found an open issue about this).
- not confirmed in the source
Quick glossary
- Matomo: An open-source web analytics platform historically forked from Piwik, typically backed by PHP and MySQL/MariaDB.
- Umami: A lightweight open-source web analytics tool built with modern stacks (Next.js) that commonly uses PostgreSQL for storage.
- PostgreSQL: An open-source relational database management system known for standards compliance and extensibility.
- MariaDB / MySQL: Open-source relational database systems frequently used with PHP applications; MariaDB is a community-developed fork of MySQL.
- Kubernetes (k8s): An orchestration system for deploying, scaling, and managing containerized applications.
Reader FAQ
Is there an official open-source Matomo-to-Umami importer?
Not confirmed in the source; the author found no OSS importer and notes Matomo Cloud has a non-open import feature.
Where can I find the migration tool used?
The author published the tool as angristan/matomo-to-umami on GitHub.
Does the tool use Matomo or Umami APIs?
No — the tool reads Matomo’s database and generates raw SQL for Umami rather than using APIs.
What data does the tool migrate?
It extracts visitor sessions and pageview events and maps common fields; for other data or edge cases, not confirmed in the source.
Migrating my web analytics from Matomo to Umami 22 December 2025 · 714 words · 4 mins free-software privacy sysadmin devops Table of Contents Finding a modern alternative to Matomo…
Sources
- Migrating my web analytics from Matomo to Umami
- Migrating from matomo to Umami – Raffaele Spinelli
- Migrate from Matomo Analytics to Umami
- GA4 to Umami: The Complete Migration Guide Without …
Related posts
- T-Ruby brings inline type syntax to Ruby and generates standard RBS
- Witr — tool that explains why a process is running on Linux systems
- How uv got so fast: design choices behind a speedy Python installer