How do I install Matomo for WordPress?

Click here to view the installation guide

How do I make Matomo for WordPress work when I have a custom content directory?

If you have configured a custom content directory using WP_CONTENT_DIR or are using symlinks, then parts of the plugin likely won’t work (eg the Matomo Reporting/Admin/Tag Manager pages) and you get a warning in the system report or an error pointing to this FAQ when you try to open for example the Matomo reporting page.

There are two ways to configure the path to the WordPress root directory that contains the file wp-load.php.

1. Through an environment variable

You can specify an environment variable (eg through apache or nginx) named MATOMO_WP_ROOT_PATH which points to the root directory of your WordPress directory. It needs to be an environment variable, defining a constant with the name MATOMO_WP_ROOT_PATH won’t work. If you set the environment variable through a web server, then only web requests will be fixed but not requests that are executed on the command line. That’s why we recommend you also add the following line to your wp-config.php which may fix report generation issues (archiving):


2. By creating a file in the plugins directory

Alternatively, you can place a file named matomo.wpload_dir.php in the WordPress plugins directory (eg wp-content/plugins/matomo.wpload_dir.php).
This file should include the path to your wp-load.php and can look like this:

<?php exit;

To avoid a PHP error should this file be opened directly you can place a comment before the directory path

<?php exit;

Make sure the configured path is an absolute path that starts with a slash or backslash (depending on the operating system).

What are the requirements for Matomo for WordPress?

You need at least WordPress 4.8+ and PHP 7.2+ as well as a MySQL database ideally running MySQL 5.5 or newer. We recommend having at least 128MB memory configured. If you have a high traffic website you may require more memory.

  • If you have WP_DEBUG enabled, then some notices re MySQL might appear which can be ignored.
  • If you have configured a custom content directory using WP_CONTENT_DIR or are using symlinks, then parts of the plugin might not work. You may be able to workaround this.
  • There may be an issue if you are using an incompatible plugin

A note on performance
Running an analytics tool within your WordPress basically causes your server to receive an extra request for each page view. If your server is already on it’s limit in terms of CPU/LOAD, then you may want to consider installing Matomo on a separate server using Matomo On-Premise, or sign up for a Matomo Cloud account where we do the hosting for you, or ask your hoster to upgrade your server.

A note on WP Multisite
Matomo for WordPress supports WP Multisite. However, there are some restrictions like you won’t be able to aggregate analytics data across blogs and if you are managing many blogs, Matomo On-Premise or Matomo Cloud might be better suited for you. Learn more about how it compares to Matomo On-Premise.

How to install Matomo
Do you meet these requirements? Or want to simply give it a try? Click here to read the instructions on how to install the Matomo for WordPress plugin in your WordPress.

If you already have a running Matomo On-Premise or Matomo Cloud
Then you will want to install the WP-Matomo Integration plugin and not our Matomo for WordPress plugin. Learn more about the differences between Matomo Analytics and WP-Matomo Integration.

What are the differences between Matomo On-Premise and Matomo for WordPress?

  • There are no users and no website management in Matomo itself. Instead users and websites are managed in WordPress. This way you only need to manage your users and sites in one place. You can still give multiple users access to your reports, you simply don’t manage them in Matomo but instead in WordPress.
  • Matomo HTTP API is not available, we recommend you use the WordPress REST API instead
  • Widgets cannot be exported, we provide shortcodes to embed reports into your website instead
  • Tag Manager is not available in WP Multisite. However, you may be able to enable Matomo Tag Manager under circumstances
  • Matomo CLI tools (console) may not work in WP Multisite
  • The entire login/logout and authentication is all done through WordPress. Therefore our login plugins like LoginSaml, Login HTTP Auth, etc. won’t work.
  • Individual Matomo core plugins cannot be disabled
  • The Matomo mobile app for Android and iOS won’t work with Matomo for WordPress
  • No custom logo can be uploaded in Matomo for WordPress
  • Matomo for WordPress focuses on simplicity by doing a lot of the work you usually have to do in On-Premise, for you. For example it automatically configures Geolocation and you don’t need to set up any cronjob to generate reports.

Download Matomo For Free Now

Why are there two different Matomo for WordPress plugins? What is the difference to WP Matomo Integration plugin?

WP-Matomo (WP-Piwik) plugin is an awesome plugin to connect your existing Matomo On-Premise or Matomo Cloud account with WordPress. The difference is that Matomo On-Premise for WordPress installs Matomo Analytics fully in your WordPress. So you get the convenience of having a powerful analytics platform within your WordPress.

If you are already using Matomo on our Cloud or On-Premise, we’d still highly recommend you use WP-Matomo. So that you get an easier way of inserting the tracking code into your WordPress site and get insights faster.

I have a high traffic website, will it be an issue to use Matomo for WordPress?

If you have a lot of traffic, we’d advise you to install Matomo On-Premise separately and use it in combination with our WordPress integration plugin WP-Matomo. There’s no specific traffic threshold we can give you on when it’s better to use Matomo On-Premise. It really depends on your server. We also need to await feedback from this beta test.

We reckon if you have more than 500,000 page views a month, you may want to think about using Matomo On-Premise with WP-Matomo instead, but this is just an estimate. In general, if the load on your server is already quite high, then it might be better to install Matomo on a separate server. See also recommended server sizing for running Matomo.

Which plugins is Matomo for WordPress known to be not compatible with?

  • Background Manager (background-manager/background-manager.php). Uses an old version of twig which may cause issues in the Matomo reporting and admin pages.
  • data-tables-generator-by-supsystic. causes some links in the Matomo reporting and admin pages to be unstyled or even disappear due to an old version of twig.

Note: This list applies to Matomo for WordPress, it does not apply to WP-Matomo Integration.

Does it support WP MultiSite?

Yes it does. Matomo differentiates between two different Multisite modes.

Matomo is not network enabled

In this mode, all settings including the tracking and access settings are managed individually for each individual blog. They cannot be managed in one central place for all blogs. Any user with the “Matomo super user” capability can change these settings.

Matomo is network enabled

In this mode, the tracking, access, geolocation and advanced settings are managed in the network admin in one place and apply to all blogs. An administrator of a blog cannot view or change these settings.

The privacy and exclusion settings, as well as any setting within the Matomo Admin has to be configured for each blog individually. They cannot yet be configured in one place meaning these settings need to be changed for each blog should any adjustment be needed. Most users find they don’t need any changes there though as Matomo anonymises the IP address by default for example.

Managing many sites?

If you have a lot of sites – or a lot of traffic in your WordPress – we recommend you install Matomo On-Premise or use the Matomo Cloud as it has these benefits:

  • Less load on your server
  • Gives you the ability to use additional features such as White Label and Roll-Up Reporting
  • You can manage all Matomo related settings conveniently in one place
  • You can integrate the tracking code in a similar way using the WP-Matomo plugin

How do I use the API in Matomo for WordPress?

Matomo for WordPress doesn’t support our HTTP API but instead supports the WordPress REST API. View the reference and more information on our developer site. You can use it to automatically create goals, fetch reports, add annotations, and more.

Do Matomo Premium Features work with Matomo for WordPress?

Most of them do. This means features like Heatmaps, Session Recordings, Form Analytics, Media Analytics, Custom Reports and many more are available for WordPress. Only a few premium features like “A/B Testing”, “White Label”, and “Roll Up Reporting” are currently not available on Matomo for WordPress.

How do I enable the Tag Manager in Matomo for WordPress when I use the WordPress Multisite feature?

By default, the Matomo Tag Manager is not enabled when you are running a MultiSite installation. This is because the Tag Manager doesn’t work if the Matomo plugin is network enabled. If you’re certain you won’t be activating Matomo in network mode, then you can enable it by adding below code to your wp-config.php file:


How do I disable the Tag Manager in Matomo for WordPress?

If you don’t want to use the Matomo Tag Manager and prefer to disable it, you need to add below code to your wp-config.php file:


How do I suppress DB errors in Matomo for WordPress?

Matomo for WordPress related DB errors may become visible in the user interface should for example WP_DEBUG be enabled. Here is what such errors might look like:

Matomo for WordPress DB Error Message

You can force the suppression of DB errors by adding the following line to your wp-config.php:


Most DB notices can be ignored in Matomo for WordPress as we’d detect them and work around them.

How do I change the timezone in Matomo for WordPress?

Matomo automatically uses the same timezone as configured in WordPress. To change the timezone follow these steps:

  • Log in to your WordPress admin dashboard
  • Go to “Settings -> General”
  • Change the timezone
  • Save the change

The timezone is often applied immediately. However, in some cases it can take up to a day. In this case you can trigger an immediate sync of the timezone by going to “Matomo Analytics -> Diagnostics -> Troubleshooting” and then clicking on the “Sync site” button.

How do I migrate all my data from Matomo for WordPress to Matomo On-Premise?

This should work using our Migration plugin. You can install this plugin on your WordPress instance. Afterwards you can for example run the command like this:

php wp-content/plugins/matomo/app/console migration:measurable --source-idsite=1  --target-db-host= --target-db-username=root --target-db-password=secure --target-db-name=matomo2

In most cases the source-idsite should be 1. You can find the correct value in the Matomo for WordPress system report under the “Matomo Blog idSite” setting.

How do I install a Matomo Marketplace plugin in Matomo for WordPress

You can install and updates for plugins from our Marketplace using the “Matomo-Marketplace for WordPress plugin” which you can download here.

Once you have downloaded the zip file, please log into your WordPress and click on “Plugins => Add new”. There you will be able to upload the zip file and activate the plugin. Alternatively, you can unzip the file and copy the files manually into your wp-content/plugins directory.

The plugin will hook into the existing “Matomo Analytics => Marketplace” link in your WordPress and add two new tabs:

  • One to install and update plugins from our Matomo Marketplace with the convenience of a click
  • One to configure the license key in case you have purchased any Premium Features so you can install & update these with the easy of a click too

How do I delete or reset the Matomo for WordPress data completely?

When you uninstall the Matomo plugin in your WordPress, all data (including all tracked data, reports, and configurations) will be deleted automatically if you use Matomo for WordPress 1.0.7 or newer. You can configure this behaviour by going to “Matomo -> Settings -> Advanced” in your WordPress admin dashboard in case you don’t want to delete any data when you uninstall the plugin.

Alternatively to the UI setting, you can also enforce a specific behaviour by defining a constant in your wp-config.php file:

define('MATOMO_REMOVE_ALL_DATA', true);
// or to never delete data from the database
define('MATOMO_REMOVE_ALL_DATA', false);

You can also manually delete all data

How do I manually delete or reset all Matomo for WordPress data?

There are three ways to completely delete all data Matomo has stored in your WordPress database and filesystem.

1. Using WP-CLI

If you have WP-CLI installed, and the Matomo plugin is still installed in your WordPress, then you can simply run this command:

wp matomo uninstall --force

Please note that you maybe want to run the plugin uninstall command afterwards as otherwise Matomo may be reset/reinstalled again immediately.

wp plugin deactivate --uninstall matomo

2. Reactivating the plugin

Enable the removing of all data as described in this FAQ and then activate the plugin again in your WordPress if possible. Then you can deactivate and uninstall the plugin in the WordPress plugins manager and all data should be gone.

3. Manually delete all data:

Follow these steps to delete the data manually:

  • Delete all tables that include matomo after the WordPress table prefix $WPTABLEPREFIX_matomo_*, for example drop all tables where the name is like wp_matomo_*
  • Delete all options from the wp_options table whose value starts with matomo%. For example using this query: delete from wp_options where option_name like 'matomo%'
  • Delete all usermeta data from the wp_usermeta table whose value starts with matomo_%. For example using this query: delete from wp_usermeta where meta_key like 'matomo_%'
  • Delete the wp-content/uploads/matomo directory
  • Delete the wp-content/cache/matomo directory if it exists


If you are using WP-MultiSite, then you also need to delete data from the wp_sitemeta table like this: delete from wp_sitemeta where meta_key like 'matomo%'

You will also need to remove the matomo folder within the uploads directory of each site. For example if the upload directories are stored in wp-content/uploads/sites/$BLOG_ID/ then you can run

rm -rf wp-content/uploads/sites/*/matomo

This should remove most, if not all of the data that Matomo stores in your WordPress DB and folder.

I have a high traffic website, how do I disable automatic execution of DB upgrades?

When you update any Matomo related plugins, we will automatically execute all upgrades these updates come with, such as:

  • New Plugin activations
  • Old plugin deactivations
  • DB schema changes
  • etc

Most DB schema changes are very fast except for major Matomo updates (version increases from say 3.0 to 4.0 or from 4.0 to 5.0). If you are using Matomo for WordPress with a high traffic website, these updates can take much longer than usual. For high traffic websites we recommend executing these upgrades on the command line. You can disable the auto upgrade after a Matomo plugin has been updated by adding this line to your wp-config.php:

define ( 'MATOMO_ENABLE_AUTO_UPGRADE', false );

You can then execute the update on the command line using this command

wp matomo update --force  (uses the WP-CLI)

If for some reason the WP CLI doesn’t work for you, you can also run our console command:

./wp-content/plugins/matomo/app/console core:update --yes

This will only work though when you are not in MultiSite and we recommend enabling the auto upgrade again after the update has been executed in case you are using our console tool.

I have an issue with the plugin, how do I troubleshoot and enable debug mode?

When you’re having issues with the plugin, we are happy to help and troubleshoot the issue.

First, you should always go to “Matomo Analytics => Diagnostics” (older versions have a menu item “Matomo Analytics => System Report”) to check if there is any error or warning. If the plugin doesn’t even install or crashes right away, you can still view the system report see further below. To help us troubleshoot your issue if there is no error in the system report, we need you to enable the debug mode (WP_DEBUG) in WordPress.

Enable debugging

To enable debugging, please edit wp-config.php file and add the following line:

 define( 'WP_DEBUG', true );

By default, the errors and warnings will be shown within the HTML pages (the other constant WP_DEBUG_DISPLAY is set to true by default). You can also choose to save all errors to a debug.log file inside the /wp-content/ directory, by adding the following line:

define( 'WP_DEBUG_LOG', true );

Learn more on the WP_DEBUG page.

If possible, we recommend also looking at your general PHP and webserver error log.

Get and copy the system report

In WordPress, go to the Admin panel, and under “Matomo Analytics”, click on “Diagnostics” (older versions have a menu item “System Report”).

Click the button “Copy system report” to copy the report to your clipboard.

Note: if you can’t even install the plugin at all, please update your wp-config.php file, and add the following line:

define( 'MATOMO_SAFE_MODE', true );

This will help making sure that the Matomo System report works even if you can’t install the plugin.

Click here for a detailed step by step FAQ on how to get the system report.

Archiving and reports not working?

Check out this FAQ.

Matomo reporting, admin, or tag manager page not working?

Check out this FAQ.

Create an issue on Github and paste the System report

Next step is to create an issue in our Matomo for WordPress issue tracker. In the issue description, you can describe your issue in as many details as possible and then paste the System Report, as well as any error or warning messages.

Then disable debug mode again

Once you are done with troubleshooting, edit wp-config.php file and set the constant to false:

 define( 'WP_DEBUG', false );

How do I prevent the Geo IP database from being downloaded into multiple directories in Matomo for WordPress when using MultiSite mode?

By default, Matomo will download and use the Geo IP DB only once for all your blogs instead of doing this for each blog. This works fine in almost every case unless you customise various parts in your Matomo such as the upload path and the directory structure etc. In this case, you can force Matomo to use a specific upload path by defining the following constant in your wp-config.php:

define('MATOMO_GLOBAL_UPLOAD_DIR', '/path/to/network/upload/directory');

This would be needed only if you are using WP MultiSite, e.g. if you are overwriting the upload path through some custom plugin.

I want to extend the WordPress plugin, where is the documentation?

We cannot wait to see what you, the community, will come up with!

We will make the documentation available closer to the release date on our Matomo Developer Zone. We’re already providing a few filters to hook into our plugin and you can also access Matomo data within any WordPress plugin.

There are so many awesome ways to make this work and to figure out how the insights could be better integrated into WordPress, so please let us know your ideas, and keep an eye out!

I cannot open the Matomo Reporting, Admin, or Tag Manager page, how do I troubleshoot it?

You click in your WordPress on “Matomo Reporting”, “Matomo Admin”, or “Matomo Tag Manager” and the page isn’t loading or only partially. This can have various reasons.

Usage of ad blockers etc

Please check your browser if you have any ad blocker extension or similar active. If so, disable it and try again. If you are using the Brave browser, you may need to disable blocking scripts, or the entire shield.

Check the System Report

Before troubleshooting any further we recommend checking the “Matomo Analytics => Diagnostics” (older versions have a menu item “Matomo Analytics => System Report”) for any errors or warnings that could maybe explain the issue.

If the page isn’t loading at all

  • If possible, open the browser developer tools to see if there is any error in the network tab. Have a look for network requests that have for example a red color or requests that show an HTTP status of 400 or higher.
  • If the page shows a 403 Forbidden error, then your server might be blocking this request because
    • You may be using some WordPress plugin that is blocking requests to plugin files
    • Your webserver might be using some security plugin that doesn’t like the URL
    • Your webserver configuration might only allow certain files to be requested through the web and you might need to whitelist our files: wp-content/plugins/matomo/app/index.php, wp-content/plugins/matomo/app/matomo.php and optionally wp-content/plugins/matomo/app/piwik.php

When you have a WordPress Security plugin enabled

Please let us know which plugin you are using by creating an issue (see below) and which feature you have enabled that might be causing this issue. We will be trying to reproduce and workaround it.

If you are using a web server like Nginx, you may need to tweak your configuration

If are using the Apache web server things should work without any issues out of the box unless a security plugin is blocking something see above. If you know you are using some other web server, for example NGINX, then you might need to whitelist certain files to be accessible by the user if you get some HTTP 403 error. These are typically:

  • wp-content/plugins/matomo/app/index.php (for the Matomo reporting UI)
  • wp-content/plugins/matomo/app/matomo.php (for the Matomo tracking)
  • wp-content/uploads/matomo/matomo.js (for the Matomo JS tracking code)

If the page is only partially loading

  • Check there is no ad blocker or anything similar active
  • If possible, clear the browser cache and reload
  • If you can, open the browser developer tools to see if there is
    • any JavaScript error in the “console”
    • any file that could not be loaded in the “network tab” (eg HTTP error 404, 403, 500, …)
  • If you see any HTTP 500 error, try to enable WP_DEBUG or check your PHP and webserver error logs if possible.
  • If HTML pages aren’t being loaded, you might want to check out this FAQ.

If the issue is not resolved, you may want to create an issue see below and let us know any insights you found.

Create an issue on Github

Next step is to create an issue in our Matomo for WordPress issue tracker. In the issue description, you can describe your issue in as many details as possible and then paste the System Report, as well as any error or warning messages you noticed. Ideally, you also let us know what webserver you are using (eg Apache or Nginx), and paste any related errors or logs from enabling WP_DEBUG if possible.

How do I find and copy the system report in Matomo for WordPress?

You can find the Matomo System Report by logging in to your WordPress Admin dashboard and clicking in the left menu on “Matomo Analytics => Diagnostics” (older versions have a menu item “Matomo Analytics => System Report”). If the plugin doesn’t even install or load, please see further below on how to get the system report to work.

On the system report page you find a button “Copy system report” at the very top. Simply click the button to copy all its content to your clipboard. The copied system report will have your URL and server paths automatically anonymised.

Now that it’s in your clipboard, you can simple paste the system report in an email or in a Github issue (right click and select “paste” in the context menu).

If the plugin doesn’t even install

If the plugin installation fails, please update your wp-config.php file and add the following line:

define( 'MATOMO_SAFE_MODE', true );

Once added, the Matomo System report should show up in the menu and you can follow the steps above. Once you copied the system report, you might want to remove the line again from your wp-config.php file and temporarily deactivate the plugin until you get further instructions from us. If you haven’t done yet, please create an issue and let us know about your problem.

If you don’t know how to find or edit your wp-config.php, we recommend asking your hoster or your system administrator for more information. There are also various tutorials available by searching for “How to edit wp-config.php” in your favourite search engine. You might also want to include the name of your hoster or control panel like How to edit wp-config.php in cpanel”.

Where do I find the source code for the Matomo for WordPress plugin?

You can find the source code for both our WordPress plugins on GitHub:

Matomo for WordPress is not showing any statistics / reports, how do I fix it?

You are using Matomo for WordPress and have enabled tracking, but no data is shown in the Summary report page or when you go to “Matomo Reporting”.

1. What is archiving?

When visitors are being tracked, Matomo stores information about each individual action your visitors take. This is called raw data. From time to time (typically every hour or so), Matomo generates aggregated reports from this raw data. For example, it will generate a report saying
5 visitors from the United States, or 3 visitors where using Firefox as a browser. This aggregated report generation is called archiving and runs in the background through WordPress Cron (WP-Cron).

2. Find out if it is actually a tracking issue, or an archiving issue

  • Go to your WordPress Admin Dashboard
  • Go to Matomo Analytics => Visitors => “Visits Log” or “Real Time”

If any of the two reports are showing data, then likely it is an archiving issue. If these two reports are not showing any data, then it might be actually a tracking issue.

We recommend you also double check the selected date. If you just installed Matomo for example, make sure you are looking at today’s data. If you have been using Matomo for a while, you might want to look at yesterday’s data or last week’s data.

If you have low traffic, you want to make sure you actually had visits on your website in that time. We recommend you access your website in incognito mode so you are logged out of WordPress. Just in case you have excluded your own IP, you might also want to access your website from your phone or so.

3. Find out when archiving ran successfully the last time

Another indicator that you are having issues with archiving might be if the last archiving cronjob was not successful in a while. To find out when it ran last successfully, go to “Matomo Analytics => Diagnostics” (older versions have a menu item “Matomo Analytics => System Report”). There you will find a section called “Crons” and it will show you when the archiving finished last.

If the date next to “Last ended” in the “Archive” row was a while back, then likely some error occurs during the archive process.

4. Are there any errors in the system report?

The next step is to check in the system report page if there are any errors or warnings that need fixing. For example, it might say there is a MySQL permission missing. Not all warnings or errors might be related to archiving and in doubt simply ping us see how to create an issue at the bottom. We’re happy to help.

5. Does archiving work when you execute it manually?

To check if archiving works when you trigger it manually, scroll to the top of the System Report page and click on Troubleshooting.

Now click on the “Archive reports” button.

It may take a few seconds or minutes for this to finish depending on your server size and the number of visits / page views your website gets. Once it is finished, check if there are any errors or warnings shown at the beginning of the page. You might see some warnings or errors looking like this (if there are any, let us know by creating an issue see below):

You will also want to check if the “Matomo Analytics => Summary” or any of the other Matomo reports are now showing data.

6. Enabling file logging

If data is still not showing up, or if the archiving worked when triggering manually but not during a cron, then we recommend enabling file logging. Make sure to have these two options enabled in your wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

Now we recommend waiting for a few hours for the cron to run again (the cron usually runs hourly). Depending on your configuration, any errors or warnings will be logged to your WordPress wp-content/debug.log file or similar. You can identify Matomo related logs when they contain the word Matomo.

If you don’t find any warnings or errors in the debug log, we recommend having a look at the PHP error log or your webserver error log if possible.

6. Create an issue

Now it is time to let us know about the problem you are experiencing by creating an issue on our GitHub issue tracker. In the issue description, you can describe your issue in as many details as possible and then paste the System Report, as well as any error or warning messages you could find.

7. Possible workarounds

It is important to always create an issue if you are having trouble with the archiving so we can fix it and also avoid the issue for other users. If for some reason the issue is not fixable, or we can’t get enough information to fix it, there may be workarounds:

Try disabling the asynchronous archiving

This may be a work around if the system report says Supports Async Archiving => Yes in the Matomo category. Then it may be possible that disabling this feature helps. You can do this by editing you wp-config.php and adding the following line:


How do I migrate all my data from Matomo for WordPress to the Matomo Cloud?

Simply get in touch with us and we will send you all the instructions for this.

How do I fix the error “Your PHP installation appears to be missing the MySQL extension which is required by WordPress.” in Matomo System Report

You are viewing the Matomo System Report in Matomo for WordPress and as part of the "Matomo Logs" section you are seeing some long HTML output where it also says "Your PHP installation appears to be missing the MySQL extension which is required by WordPress." (In German the message might be like "Deine PHP-Installation scheint nicht über die von WordPress benötigte MySQL-Erweiterung zu verfügen.").

Additionally, in the section "Matomo: Optional checks" you are seeing something like "Supports Async Archiving: Yes".

If this applies to you, it looks like the PHP Mysqli extension is not available when a command is executed through the command-line interface (CLI). The Mysqli extension is basically only available in a web request. You can likely fix this issue by adding this line to your wp-config.php:


Alternatively, you may ask your system administrator or hoster whether they can enable the Mysqli extension for PHP-CLI.

How do I migrate all my data from Matomo On-Premise to Matomo for WordPress?

This is currently not supported / tested as we do not recommend doing this. Matomo On-Premise will run faster and you can have Matomo On-Premise for performance reasons on a separate server if needed. You will have a lot more options, plugins, etc available. We strongly recommend you stay with Matomo On-Premise if possible.

Should you still want to migrate to Matomo for WordPress read more about this in our issue tracker.

How do I hide my WordPress login URL when someone accesses a Matomo report directly?

If you are using a plugin like “WPS Hide Login” to hide your WordPress Admin login URL, then Matomo may expose your WordPress login URL depending on the plugin you are using. This happens when you are logged out, and you are accessing the Matomo reporting or admin UI directly through a URL like this:

If you are not logged in, Matomo will then redirect you to the WordPress login URL, ask you to log in, and redirect you back to the selected Matomo page. If you prefer a user to be redirected to the log in page instead, you can add the following snippet to your wp-config.php:

define( 'MATOMO_LOGIN_REDIRECT', 'frontpage' );

Once configured, this will redirect the user to your homepage instead of the login page.

If you are using the “WPS Hide Login” in particular, then we automatically redirect you to the home page and you could force the behaviour to show the login page instead by adding this snippet to your wp-config.php

define( 'MATOMO_LOGIN_REDIRECT', 'login' );

Are you using a different plugin to hide the login URL? Please let us know and we might be able to add support for it automatically without needing to configure anything.

How do I make Matomo for WordPress work when it is behind a CDN or proxy?

If you are using a service like CloudFront or CloudFlare, then you will need to follow these instructions to make sure everything works as expected:


Make sure all cookies are forwarded eg to wp-content/plugins/matomo/app/* as otherwise the standalone Matomo reporting UI, Matomo Tag Manager and the Matomo Admin UI won’t be able to recognise your WordPress login.


To prevent for example devices from being not detected you should ideally exclude the CDN feature for the wp-content/plugins/matomo/app/matomo.php tracking endpoint if any possible. This prevents that the tracking endpoint will be ever cached and that the original user agent will be forwarded instead of for example Amazon CloudFront.

Trusted host warning

When viewing the Matomo reporting UI you may see a trusted host warning that says something like “You are now accessing Matomo from ABC, but Matomo has been configured to run at this address: XYZ. Matomo may be misconfigured”. You can workaround this by editing the Matomo config file. This FAQ describes how you can find the path to the Matomo config file.

Now that you know where the config file is located, edit the config file and add a new line below the already existing line that starts with trusted_hosts[] = "...". Enter the actual Matomo URL like this:

trusted_hosts[] = "https://the-url-that-was-already-defined..."
trusted_hosts[] = "https://my-actual-matomo.url"

Matomo URL (eg logo not showing or wrong link in an email)

You might also need to configure the proxy header URL as described in this FAQ in your config file (see how to locate the path to the config file). This is for example the case if the Matomo logo is failing to load. It might also fix an issue where a sent email from Matomo points to your internal proxy URL instead of the actual Matomo URL.

For example, if you are using CloudFlare, you may need to add this to your config file under the [General] section:

proxy_client_headers[] = HTTP_CF_CONNECTING_IP

IP detection

If the location (continent, country, …) of your visitors is not detected correctly, then you likely need to go “WordPress Admin -> Matomo Analytics -> Settings -> Advanced” and configure an alternative Proxy IP Header. Click here to get detailed instructions.

My WP-Cron is not working, how do I enable browser archiving?

We only recommend doing this if you have little traffic and generating reports for your Matomo is fast. Generating the reports on demand when you view them will make your Matomo slow otherwise. If for some reason you want to enable the browser archiving, for example because you are a developer or because you are having other issues, you can enable this feature by adding the following line to your wp-config.php:


Does Matomo for WordPress run on

We don’t think so. As mentioned on the incompatible plugins guide, WordPress has found that SQL-heavy plugins can put a high strain on their servers and we reckon this plugin will fall into this category.

How can I configure the tracking code manually when I have WordPress network enabled in MultiSite mode?

This applies only if you have Matomo for WordPress network enabled in MultiSite and you want to configure the tracking code manually. As the tracking code is saved for the network and will be used across all blogs, you need to use variables in the tracking code which will be replaced with the actual values on demand:

  • {MATOMO_IDSITE} – will be replaced eg with 1
  • {MATOMO_API_ENDPOINT} – will be replaced eg with
  • {MATOMO_JS_ENDPOINT} – will be replaced eg with

Here’s an example:

<!-- Matomo -->
<script type="text/javascript">
var _paq = window._paq = window._paq || [];
_paq.push(['setTrackerUrl', {MATOMO_API_ENDPOINT}]);
_paq.push(['setSiteId', '{MATOMO_IDSITE}']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.async=true; g.defer=true; 
<!-- End Matomo Code -->

How do I fix the Proxy Header warning in the Matomo for WordPress system report?

You are viewing the Matomo for WordPress System Report and you are seeing a message that says something like “A proxy header is set which means you maybe need to configure a proxy header in the Advanced settings to make location reporting work.”

This likely happens because you are using a CDN like AWS CloudFront or a proxy like CloudFlare. What this warning indicates is that the geolocation detection in your Matomo might not work correctly. This means Matomo might detect the wrong region, country, or even continent when a visitor visits your website.

To fix this warning follow these steps:

  • In your WordPress Admin Dashboard click in the left menu on “Matomo Analytics -> Settings”
  • Click on the “Advanced” tab
  • Now you should see the setting for the proxy headers which looks like this

To know which of these values to choose first check what your actual IP address is.

Now compare the value of each option to find the entry that shows the same IP address. You can ignore any value that says “No value found”. An entry saying “” is likely also not correct unless you are a developer and are using WordPress only on your local computer. There should be one or multiple entries showing your actual IP address. Select one of these values and click “Save changes”. The warning should be gone afterwards.

If multiple options show your IP address, it’s likely to fine to choose any of them.

Learn more about how to make Matomo for WordPress work with a CDN or Proxy if you run into other issues.

How do I find the path to the Matomo config file in Matomo for WordPress?

The Matomo config file is typically located in $WordPressRoot/wp-content/uploads/matomo/config/config.ini.php.

If this is not the case, please open the page Matomo Analytics -> Diagnostics within the WordPress Admin UI and look out for the row that starts with “Config exists”. It should be one of the first rows and you will find the path to the config file on the right. The path ends with config.ini.php.

Config path shown in the Matomo diagnostics page in WordPress

How do I fix the error “WP DB Error: [1146] Table ‘[…].wp_matomo_option’ doesn’t exist”?

It looks like maybe for some reason Matomo was not correctly installed. In the past these were known reasons for this:

  • The WP-Matomo Integration plugin is installed and configured to run in PHP mode. If that’s the case, we should detect this in the system report
  • The WordFence plugin is causing an issue. A user installed Matomo Beta, uninstalled it, and later installed it again from the WordPress directory and then this error appeared. It was fixed by deleting all the DB entries that contained matomo from these tables: wp_wfKnownFileList and wp_wfFileMods as well as the external_updates-matomo entry from the wp_option table. This error likely only occurred while using the initial beta which was hosted on our servers and then updating the plugin from the WordPress directory. Please let us know if you still experience this issue.

If you still have this issue, please check out the Matomo system report and create a new issue. It be great if you could include the anonymized system report in the issue.

How do I prevent Matomo cache file changes to show up in Ninja Firewall

If you are using the Ninja Firewall WordPress plugin, you may notice that Matomo cache files can show up as part of the list of changed files. Here’s an example image of what it might look like:

To workaround this follow these steps:

  • click on the “Delete snapshot” button in NinjaFirewall -> Monitoring
  • modify the list of files and folders to exclude and append “,/wp-content/cache/matomo/“. It is important you also append the leading comma. If the “wp-content/cache” directory is not writable in your Matomo, the directory you need to exclude may be “,/wp-content/uploads/matomo/tmp“. The Matomo system report will show you which “tmp directory” is actually used.
  • click on “Create snapshot”
  • from now on these files should no longer show up