How to migrate from Google Analytics to Matomo
Import GA4 history with the free importer, swap the Google tag for Matomo, rebuild key events as goals, settle consent and cut over after a parallel run.
- Workflow and data
- 6 steps
In short
- Matomo’s free Google Analytics Importer brings GA4 history across as aggregated reports in a new site; it cannot import into an existing site or be merged into one later.
- On imported months the visitor log, segments and custom reports do not work, weekly and monthly reports have no unique visitors, and GA4 goals arrive without names or revenue.
- Key events are rebuilt by hand as Matomo goals, events and custom dimensions, and ecommerce tracking is switched on per site before the tag goes live.
- Both tags run side by side under the same consent conditions, and the Google tag comes off only once each report owner accepts the figures.
On this page (9)
Moving from Google Analytics to Matomo is a re-tagging with a history import beside it. Matomo’s free importer reads your GA4 property through Google’s API and brings the history across as daily reports, not as individual visits. Everything Matomo measures from then on comes from its own tracker, so the real work is on your sites and apps: replacing the Google tag, rebuilding the key events you report on, and agreeing which consent setup applies. This guide covers the order we run it in, and the places it usually goes wrong.
Why teams move from Google Analytics to Matomo
Three reasons come up again and again.
- Every visit lands in your database. With Matomo, each hit goes to a tracking hostname you own and is stored in a MariaDB database in the location you choose. No visit data goes to Google or to the makers of Matomo.
- The raw data is yours. Matomo does not sample reports, and the raw visits stay in your database for as long as your retention allows, to query through its API or in SQL.
- Consent on your terms. Matomo can track without cookies, wait for consent, or enforce per site the configuration it documents for the French CNIL’s consent exemption. The setup follows your data protection officer’s decision, not a vendor’s defaults.
What you give up is real. Audiences built from site behaviour for Google Ads have no equivalent, and history before the move arrives as reports only, so you cannot open an old visit or apply a new segment to it. Funnels, heatmaps, session recordings, A/B tests and custom reports are paid Matomo plugins. And someone has to run Matomo, which is the part Pilae takes on.
Step 1: inventory properties, key events and tags
The import and the rebuild both start from this list.
- Properties and data streams. List every GA4 property with its web and app streams. Each imported property becomes one Matomo site, created by the importer.
- Key events. In the property’s Admin, under Data display, the Key events list shows what is counted as a conversion, and the Events list shows every event with its toggle. Note each key event’s counting method, once per event or once per session.
- Custom definitions. Note each custom dimension and its scope: event, user or item. Matomo has visit and action dimensions, so item-scoped ones have no home.
- Ecommerce events in use, such as
view_item,add_to_cartandpurchase, and the shop platform that sends them. - Where the tag lives: the
gtag.jssnippet in a page template, a Google Tag Manager container, a CMS plugin or a mobile app. - Who reads what: the reports, Looker Studio dashboards and Google Ads links people use, each with an owner.
Each line ends with a decision: rebuild, replace or drop. Key events nobody reports on are best dropped now rather than rebuilt.
| Google Analytics 4 | Matomo |
|---|---|
| Property | Site, created by the importer |
| Web data stream | The site’s JavaScript tracker or Tag Manager container |
| Event | Event: category, action, name and numeric value |
| Key event | Goal |
| Custom dimension, event scope | Custom dimension, action scope |
| Custom dimension, user scope | Custom dimension, visit scope |
| Custom dimension, item scope | No equivalent |
| Ecommerce events | Ecommerce tracking, enabled per site |
| Google Tag Manager | Matomo Tag Manager, which ships with Matomo |
| Internal traffic filter | Excluded IPs and the ignore cookie |
| Funnel exploration | Funnels, a paid plugin |
| Audiences for Google Ads | No equivalent |
Step 2: import the history with the Google Analytics Importer
The importer creates the site the tracker will report into, so it runs first. Matomo documents the setup in Setting up a Google Analytics import.
- Install the plugin. Install and activate GoogleAnalyticsImporter from the Matomo Marketplace. It is a free GPL plugin. Matomo lists its requirements: PHP allowed to run
exec()orshell_exec()and to start the command-line PHP from a web request,nohupon the server, and archiving from cron. - Create a Google Cloud project for the import, and in APIs & Services, Library, enable the Google Analytics Data API and, for GA4, the Google Analytics Admin API.
- Set up the OAuth consent screen. An Internal audience needs Google Workspace and has no expiry. An External app starts in testing mode, where the authorisation expires after seven days, so Matomo recommends publishing it. Matomo also says the app does not need Google’s verification, and that uploading a logo can trigger one.
- Create the OAuth client, of type Web application, with your Matomo domain as the authorised JavaScript origin and your Matomo URL followed by
/index.php?module=GoogleAnalyticsImporter&action=processAuthCodeas the redirect URI. Download its JSON file. Google accepts a redirect URI only over HTTPS on a host whose top-level domain is public, so a Matomo interface on a made-up internal domain is refused: give it a name under your own domain that resolves only on your network. - Authorise Matomo. As a superuser, open Administration, System, Google Analytics Import, choose the advanced OAuth client configuration, upload the JSON file and click Authorize.
- Schedule the import. Choose the GA4 import type and the property, and set the End Date to the day before Matomo starts tracking. Tick Mobile App for an app property: Matomo warns that without it the import may fail when the property has no URL. Dimensions Matomo does not support can be kept through extra custom dimension mappings, each of which takes one custom dimension slot.
The same import runs from the console, which is easier to watch on a long history:
./console googleanalyticsimporter:import-ga4-reports \
--property="properties/123456789" --dates=2023-01-01,2026-11-30
# Resume an interrupted import into the site it created
./console googleanalyticsimporter:import-ga4-reports \
--property="properties/123456789" --dates=2023-01-01,2026-11-30 --idsite=4
Google caps how much each property can be queried per day and per hour, and Matomo’s guide says a long history therefore runs over several days until the whole data set is in. Progress shows in the Import Jobs table on the same page, with one log per job in Matomo’s tmp/logs directory.
What the Google Analytics import brings across
Imported
- Aggregated reports, one day at a time, into a new site
- Pages and page titles; app screens as page titles when Mobile App is ticked
- Goal conversions, without the goal’s name, revenue or conversion rate
- Ecommerce reports, without product conversion rates and visits
- Unsupported dimensions, where you map them to custom dimensions
Not available on imported months
- Individual visits: the visitor log and the ecommerce log stay empty
- Segments and custom reports
- Unique visitors and users for weeks, months and other periods longer than a day
- Item-scoped custom dimensions
- Funnel and media reports
When the import finishes, back up the Matomo database. Matomo’s guide warns that imported data, once purged, can only be imported again from Google Analytics, and is gone for good if the property has been deleted. Matomo needs access to Google only while the import runs, so remove it afterwards.
Step 3: rebuild key events as goals, events and dimensions
Configure the site before any traffic arrives. In Administration, Websites, Manage, set the time zone and currency to the GA4 property’s, so daily figures line up, and switch Ecommerce to enabled if you sell online: unlike GA4, Matomo needs it switched on per site.
- Custom dimensions are created under Administration, Websites, Custom Dimensions. Matomo provides a limited number of visit and action dimensions by default, more are added from the console, and a custom dimension cannot be deleted from the interface, only deactivated, so plan them from the inventory rather than creating them as you go.
- Events. A GA4 event carries named parameters. A Matomo event has a category, an action, an optional name and an optional numeric value, plus any custom dimensions. Map each parameter you report on to one of those before rewriting the calls.
- Goals. Create each goal under Goals, Manage Goals. A goal is triggered when a visitor visits a given URL or page title, sends an event, downloads a file, clicks a link to an external website or stays a certain time, or manually from code with
trackGoal. By default a goal converts once per visit, which matches GA4’s once-per-session counting; Allow Goal to be converted more than once per visit matches once per event. Revenue is optional. - Ecommerce.
view_itembecomessetEcommerceView,add_to_cartbecomesaddEcommerceItemfollowed bytrackEcommerceCartUpdate, andpurchasebecomestrackEcommerceOrder. Matomo does not take a list of items with the order: it includes the products already added to the cart. For the common shop platforms, Matomo lists ready-made integrations.
// GA4: gtag('event', 'sign_up', { method: 'email' });
_paq.push(['trackEvent', 'Account', 'Sign up', 'email']);
// GA4: gtag('event', 'purchase', { transaction_id: 'T-1042', value: 129, items: [...] });
_paq.push(['addEcommerceItem', 'PLAN-ANNUAL', 'Annual plan', 'Plans', 129, 1]);
_paq.push(['trackEcommerceOrder', 'T-1042', 129]);
Amounts are numbers, not strings. With Matomo Tag Manager, the same events and goals are tags fired by triggers, which is usually tidier than editing page templates.
Step 4: put the Matomo tracker on every site and app
Choose how the tag is delivered. Each site’s code is under Administration, Websites, Tracking Code, and most sites use the JavaScript tracker. Where Google Tag Manager is in use today, Matomo Tag Manager is the natural replacement. Matomo describes the move as manual: create the container and its environments, recreate the variables, then the triggers, then the tags, insert the container code near or in place of the GTM snippet, preview and debug, then publish a version. It offers fewer tag types than GTM, and a custom HTML tag covers much of the gap. For the parallel run alone, Matomo also documents loading its tracking code through an existing GTM container as a Custom HTML tag, which changes no page template. Mobile apps report through Matomo’s SDKs for Android and iOS, which ship with the next app release, so plan the parallel run around the app stores.
Apply the consent decision. Matomo’s JavaScript tracker has three documented modes, the first two described in its consent guide and the third in its FAQ on going cookieless:
| Mode | Call | Before consent |
|---|---|---|
| Tracking consent | requireConsent |
No tracking request is sent, no cookie set |
| Cookie consent | requireCookieConsent |
Requests are sent, without cookies |
| No cookies | disableCookies |
Matomo sets no tracking cookies at all |
Without cookies, returning visitors are recognised less reliably, which Matomo notes affects report accuracy. For France, Administration, Privacy, Compliance applies the CNIL configuration per site: IP addresses masked by three bytes, the visits log and visitor profiles off, User ID off, raw data retention capped and ecommerce restricted. The opt-out still has to be placed on your site by hand. Matomo’s own position is that where the law requires consent for any client-side tracking, its JavaScript tracker should be treated as needing it. In Switzerland, the reference is the FDPIC’s guidelines on cookies and similar technologies. The choice belongs to your data protection officer, and we configure what they decide. With Tag Manager, Matomo publishes integration guides for several consent management platforms.
Exclude your own traffic. GA4’s internal traffic rules become IP exclusions: Administration, Websites, Settings holds the global list of excluded IPs, and each site can add its own. People who work from changing addresses can set Matomo’s ignore cookie from their personal settings, under Exclude your visits using a cookie. Exclusions apply from the moment they are set, never to visits already recorded, so set them before the tag goes live.
Step 5: run both tags and compare
Matomo starts tracking the day after the import’s end date, with the Google tag still in place. Both tags must load under the same consent conditions: Matomo points out that when one script is allowed and the other is not, the two tools count different visits.
The parallel run, in order
- Agree the gaps: Before anyone compares, owners hear which metrics the two tools define differently.
- Same days: Each report is compared on the same pages and the same closed days.
- Full cycle: Both tags run through one reporting cycle, monthly reports included.
- Sign-off: Each owner accepts the Matomo figures, or the gap is traced to a configuration.
Matomo’s own guidance is that visits and pageviews typically differ by no more than 5 to 10 percent when both tools are correctly configured, and that larger gaps usually mean a configuration problem. The usual causes it lists are consent set differently for each tag, bot traffic (by default Matomo’s JavaScript tracker records only browsers that run JavaScript), sampling in Google Analytics, visitors counted without cookies, and campaign attribution: Matomo does not carry a campaign across visits by default, so some visits GA4 credits to a campaign appear as direct in Matomo. Entrance and exit rates are also defined differently, so they are compared as trends, not as numbers.
Step 6: remove the Google tag and close the property
- Remove the tag from every site and app once its owners have signed off: the
gtag.jssnippet, the GA4 tags in Google Tag Manager, or the CMS plugin. Remove the GTM container itself once Matomo Tag Manager carries everything it did. - Update the privacy notice. Matomo recommends naming Matomo in it and including the opt-out.
- Revoke the importer’s access in your Google account, and delete the OAuth client and its Cloud project once no further import is planned.
- Keep or delete the GA4 property under your own retention policy. Matomo’s imported reports no longer depend on it, but a re-import would, so delete it only once the Matomo database with the imported history is in your backups.
Running Matomo in production
A Matomo that a whole organisation reports from needs more than the default install.
- MariaDB or MySQL. PostgreSQL is not supported. The raw visit tables grow with traffic, and the database moves to its own machine as they do.
- Archiving from cron. Reports are built ahead of time from the raw visits by
core:archive. Browser-triggered archiving turns a busy dashboard into a long query, so it is switched off. - A public tracker and a private interface. Browsers must reach
matomo.php,matomo.js, the opt-out and the Tag Manager containers. Nothing else needs to be public, and Matomo must record the visitor’s address from the forwarded header, not the address of the proxy in front of it. - Geolocation. Without a GeoIP database, Matomo guesses the country from the browser language and records no region or city.
- Retention. Raw visits older than the agreed period are deleted once archived, and the reports built from them stay. Imported history exists only as reports, so the deletion of old reports stays off.
- Sign-in. LDAP comes from the free LoginLdap plugin from the Matomo team, which synchronises users at each login. SAML is the paid Login SAML plugin from InnoCraft. OpenID Connect, for Keycloak or Entra ID, comes from community plugins rather than the Matomo team: the LoginOIDC plugin is no longer maintained and points to a fork, RebelOIDC, which documents its Keycloak settings. We check which one is maintained before relying on it.
Pilae operates Matomo this way: a dedicated machine with MariaDB, core:archive run from cron every hour with an alert when a run fails, the tracker published through the gate on a hostname you choose, and the interface on your private network, behind sign-on. The database and the configuration are backed up daily, encrypted, to an offsite location in the country your contract names, and on Enterprise a restore test every month is recorded in the console. Upgrades go through the Pilae Agent: timed on a copy, approved by you and applied in your window. It runs on your premises or on dedicated machines in Pilae Cloud.
Let Pilae run the move
Pilae runs Google Analytics to Matomo migrations at a fixed price: the inventory, the history import, the goals, events and ecommerce rebuilt, the tag swap on every site and app, the consent setup your data protection officer decides, the parallel run and the cutover. Where your requirements need premium plugins, the licences are named in the proposal. Then we operate Matomo for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us which sites and apps you measure and we will scope it.
Questions
Can Matomo import our Google Analytics history?
Can the history go into the site we already track in Matomo?
Do we still need a cookie banner with Matomo?
Is Matomo open source?
How long does a Google Analytics to Matomo migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
