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):

php
define('MATOMO_SUPPORT_ASYNC_ARCHIVING', false);

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;
/var/www/html/wordpress

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

<?php exit;
#/var/www/html/wordpress

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 for WordPress. 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)

The WP-Matomo plugin is an awesome plugin used to connect your existing Matomo On-Premise or Matomo Cloud account with your WordPress website.
So if you already have Matomo setup using one of these options, then installing WP-Matomo is the easiest and quickest solution to get your tracking code installed on your WordPress website.

Matomo for WordPress

Matomo for WordPress installs a complete version of Matomo onto the same server that your WordPress website is running on (Uses the same database as your WordPress website). This gives you the convenience of having a powerful web analytics tool installed and hosted completely within your WordPress website without needing anything extra. This version is the core version of Matomo and does not have any of the premium features. (These can be purchased separately)

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.

How do I set user permissions in Matomo for WordPress (WordPress Users Permissions)?

As there are no users and no website management in Matomo for WordPress, user permissions are assigned using WordPress Roles.

To access the permissions for Matomo for WordPress follow these steps:

  1. Hover over the “Matomo Analytics” drop down menu on the left hand side of your WordPress Admin page

  2. Click on “Settings” in the menu that opens

  3. Then go to the “Access” panel within the Matomo Analytics Settings page

  4. Here you will find the different WordPress roles (Editor, Author, Contributor, Subscriber, and possibly others like Customer, Shop manager).
    You can assign these user roles to one of the Matomo roles such as “None”, “View”, “Write” and “Admin”

Alternatively you can assign individual users roles by going to their user settings in WordPress and assigning them one of the following Matomo roles: Matomo View, Matomo Write, Matomo Admin, Matomo Super User.

A user with role “administrator” in WordPress automatically has the Super User role in Matomo for WordPress.

Learn about the differences between these Matomo roles: View, Write, Admin, Super User.

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.
  • tweet-old-post-pro (Revive Old Posts Pro Add-on). Archiving (report generation) may fail. A workaround might be to follow the last step in this faq which suggests to add “define( 'MATOMO_SUPPORT_ASYNC_ARCHIVING', false );” to wp-config.php.
  • SecuPress: If reports aren’t being generated then you may need to disable the feature “Firewall -> Block Bad Request Methods” in SecuPress (if it is enabled) or follow the last step in this faq which suggests to add “define( 'MATOMO_SUPPORT_ASYNC_ARCHIVING', false );” to wp-config.php.

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.

Does Matomo for WordPress work with the Matomo Mobile app?

Unfortunately not. The Matomo Mobile app for Android and iOS doesn’t work with the Matomo for WordPress app currently because the mobile app doesn’t support the WordPress JSON API. If this is important to you, you may want to use Matomo On-Premise or the Matomo Cloud instead.

Want to stay up to date when anything on this changes? Follow the progress in the Matomo Mobile issue tracker.

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:

define('MATOMO_ENABLE_TAG_MANAGER', true);

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:

define('MATOMO_ENABLE_TAG_MANAGER', false);

How do I find the JavaScript tracker URL that is used in Matomo for WordPress?

  • Log in to your WordPress Dashboard
  • In the left menu click on Matomo Analytics -> Settings. You should now be in the tab for the “Tracking” settings.
  • Locate the setting for “Endpoint for JavaScript tracker” (likely at the very end)
  • Click on the question mark on the right
  • The help text should appear showing you the path to your JS tracker file
  • It’s typically https://yourdomain/wp-content/uploads/matomo/matomo.js unless you change the setting to Rest API in which case it be usually something like https://yourdomain/wp-json/matomo/v1/hit/

Alternatively, you can also find the path to the JS tracker file in the diagnostics report by clicking in the WP admin left menu on “Matomo Analytics -> Diagnostics” and then locating the “Matomo -> Endpoints” section.

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:

define('MATOMO_SUPPRESS_DB_ERRORS', true);

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=192.168.1.1 --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

There are three ways you can install a Matomo Marketplace plugin. We recommend installing plugins through our Matomo Marketplace plugin as this will automatically install a version that is compatible with your Matomo for WordPress and it will also notify you when there are updates available. Updating a plugin will be as easy as any other WordPress plugin with the Matomo Marketplace plugin.

Option 1: Using the Matomo Marketplace plugin

Step 1: Installing the Matomo Marketplace plugin

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

Step 2: Installing a plugin from the Matomo Marketplace

Now that you have installed the Matomo Marketplace plugin, you can easily install any plugin from the Marketplace.

  • Go the WordPress Admin dashboard
  • Click in the left menu on “Matomo Analytics -> Marketplace”
  • In the top click on the tab “Install plugins”
  • Search for the plugin you want to install
  • Click on “Install” below the plugin name
  • Then activate the plugin

Option 2: Manual upload via WordPress Admin

  • Download a plugin from the Matomo Marketplace
  • Log into your WordPress Admin as an administrator
  • Go to “Plugins -> Add New”
  • Click the “Upload plugin” button at the top of the screen
  • Select the previously downloaded zip file
  • Click on the “Install Now” button
  • Click on the “Activate Plugin” button

Option 3: Manual installation

Download any plugin from the Matomo Marketplace, extract the downloaded zip file, and upload it to your web server using an FTP application or using SSH into the wp-content/plugins directory. Learn more.

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

Multisite

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.

If you run into any issues please check out our upgrade troubleshooting guide.

How do I troubleshoot a failed database upgrade in Matomo for WordPress?

First, check your system report whether it has any plugin_update errors like in the screenshot below. This error would be shown right in the beginning of the system report:

If that’s the case and the same error appears multiple times, please reach out to us and include the copied system report. There is a button at the top of the page to copy an anonymised version of the system report. If you prefer, you can also create an issue on our GitHub issue tracker instead of contacting us.

If such an error is shown, but the same error message isn’t shown multiple times, then the error might eventually go away the next time the updater runs. You could for example manually trigger the update again to see if it fails with the same error message as before (see below for how to trigger a database upgrade manually).

If that’s not the case, it seems like there is no issue and if previously an update error, it fixed itself by retrying the update.

How do I know if an upgrade is outstanding or currently in progress in the background?

Locate below entries in the system report to see if any upgrade is still outstanding or currently in progress.

How can I trigger a database upgrade manually?

From the system report click in the top on the “Troubleshooting” tab and then click on the button “Run updater”. This will trigger the update and if any error happens, WordPress should show a detailed error message. If an error happens, click on the button again and see if the same error appears. If that’s the case, reach out to us and include a copy of the system report.

The upgrade takes too long and always times out, can I execute the upgrade on the command line?

Yes, there are two ways:

  • Using the WordPress CLI: wp matomo update --force
  • Using the Matomo CLI (won’t work in MultiSite installations): cd /your/path/to/wp/wp-content/plugins/matomo/app && ./console core:update

Prefer to always execute the updates on the command line instead of executing them on demand using the UI? Add the following code to your wp-config.php and make sure to always run one of the above commands after executing the plugin

define( 'MATOMO_ENABLE_AUTO_UPGRADE' , false);

How do I view all outstanding database queries so I can execute them manually in the database directly?

This is currently only supported on the CLI when not using MultiSite. By executing the Matomo command core:update you will see a list of all database upgrades that need to be executed. You then also have the option to directly execute these updates on the command line.

cd /your/path/to/wp/wp-content/plugins/matomo/app
./console core:update

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 WordPress.org 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.

How do I disable all logging?

If you have WP_DEBUG always enabled and find Matomo for WordPress is logging not useful messages you can disable the logging of Matomo specific log messages by adding the following line in your wp-config.php (requires version 1.3.1 or newer):

define( 'MATOMO_DEBUG', false );

How do I log all messages?

If you want the plugin to log all messages (for debugging purposes), add the following line to your wp-config.php (requires version 1.3.1 or newer):

define( 'MATOMO_DEBUG', true );

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:

define( 'MATOMO_SUPPORT_ASYNC_ARCHIVING', false );

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:

define('MATOMO_SUPPORT_ASYNC_ARCHIVING', false);

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:

https://example.com/wp-content/plugins/matomo/app/index.php

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:

Cookies

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.

Tracking

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:

define('MATOMO_TRIGGER_BROWSER_ARCHIVING', true);

Does Matomo for WordPress run on WordPress.com?

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 do I fix the error “AddHandler not allowed here”

If you are using Apache and have disabled the “AddHandler” feature then you might get an error message similar to this:

/wp-content/plugins/matomo/.htaccess: AddHandler not allowed here, referer: ...

To disable add handler in our .htaccess files, simply add the following line to your wp-config.php:

define('MATOMO_DISABLE_ADDHANDLER', true);

Please note that it might take an hour or more until the cron executes the task to disable this feature.

This feature requires Matomo for WordPress 4.0 or newer and it requires the .htaccess files to be writable by your webserver.

If you later decide to enable AddHandler again, then you will need to either update the plugin or re-upload the Matomo for WordPress plugin.

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 https://example.com/wp-content/plugins/matomo/app/matomo.php
  • {MATOMO_JS_ENDPOINT} – will be replaced eg with https://example.com/wp-content/uploads/matomo/matomo.js

Here’s an example:

<!-- Matomo -->
<script type="text/javascript">
var _paq = window._paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
_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; 
g.src={MATOMO_JS_ENDPOINT}; 
s.parentNode.insertBefore(g,s);
</script>
<!-- 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 “127.0.0.1” 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