What version of Matomo do I have?

There are several ways to know which version of Matomo (Piwik) you are using:

  • In the top right menu, click on “Help” icon. The title of the Help will say “About Matomo X.Y.Z” (X.Y.Z being the Matomo version).
  • or in the top right menu, click on “Administration”, then click on “API” in left menu. Scroll down to the API.getPiwikVersion and click on the Example link to view your Matomo version.
  • or look in the file core/Version.php: you can download this file from your FTP server, inside this file will be the version number you are currently using.

If you want to know which version is currently the most up to date version of Matomo, click here.

What should I do when I want to update Matomo to the latest version?

Updating Matomo (Piwik) is easy and we hope you will always use the latest version of Matomo! It is possible to update from any old version to the latest one. Please see the Update guide for further instructions.

How do I backup my MySQL database?

Please see the WordPress guide on how to backup your database.

How do I restore my MySQL database?

Please see the WordPress guide on how to restore your database from backup.

How do I enable Maintenance mode (to display a maintenance message in Matomo, and disable tracking) prior to updates?

You can set a setting in your config/config.ini.php file as explained in this FAQ.

What should I do when the upgrade failed with “Syntax error or access violation: 1142 INDEX command denied to user”

Ask your sysadmin to GRANT your database user INDEX privilege. This is required to CREATE, DROP, and ALTER indexes, and allow Matomo (Piwik) to update successfully.

After the update, I get sql errors, I would like to try the update again. How do I force Matomo to re-upgrade the database from a past version?

It may happen in rare cases that Matomo (Piwik) believes it has upgraded to a newer version, but that the database itself was not actually upgraded. This FAQ explains how to re-run the database upgrade from a particular version.

For example, this could happen if the database crashed or overloaded during the DB upgrade (we recommend to enable maintenance and run the ugprade in the command line). It could also happen if the new Matomo files in core/Updates/ haven’t yet been uploaded to the latest files, but a Matomo user visits the Matomo UI and issues the partial upgrade leading to the errors.

As a result SQL error messages are often printed in some – or all – the reports. Errors messages such as

Error trying to execute the query 'CREATE TABLE [...]  Base table or view already exists: 1050 Table exists


SQLSTATE[42S22]: Column not found: 1054 Unknown column on clause


SQLSTATE[42000]: Syntax error or access violation: 1091 Can't DROP X check that column/key exist


Error trying to execute the query 'ALTER TABLE' SQLSTATE[42S22]: Column not found: 1054 Unknown column


Error in Matomo (tracker): Error query: fetch() failed: Unknown column '...' in 'field list'

The good news is that it possible in all cases to resolve the issue and not experience any data loss or other problem!

You can manually tell Matomo to run the upgrade again by executing the following SQL query (eg. using a tool such as phpMyAdmin):

UPDATE `matomo_option` SET option_value = "1.X" WHERE option_name = "version_core";

Replace 1.X with the version you were using prior to upgrading, for example “1.10”. After running this query, visit Matomo: you should see the upgrade screen again. You can run the upgrade in the command line if your Matomo is large, or simply click the button and wait until completion.

If you still have problems, you can get help in the forums or contact Support team.

How do I upgrade a large Matomo instance without losing any tracking data?

If you have a large Matomo (Piwik) instance, upgrading to the latest Matomo version may take a long time (if one of the newest Matomo releases include database schema changes).

To upgrade your large Matomo instance, follow the manual three step procedure. This includes putting Matomo UI and Tracker in maintenance mode, and run the core:update command in the console. While Matomo Tracker is in maintenance mode, no data is being collected in the database. Therefore you may lose data for the few hours when Matomo was in maintenance.

This FAQ explains how to import the missing tracking requests in Matomo.

You have two options.

Option 1

During maintenance, visitors on your websites and mobile apps are still issuing the tracking requests. These piwik.php? tracking requests are stored in your Matomo server access logs files. Once the upgrade to the latest Matomo version is successful, you can create a new log file that contains all these piwik.php requests (for the time window that Matomo was in maintenance mode and not tracking).

Then you can replay this log file in Matomo which will backfill all your data: learn more in this FAQ.

Option 2

The second option requires the use of the QueuedTracking plugin with MySQL (or Redis).

  1. Install and setup QueuedTracking plugin.
  2. Enable writing requests into the queue
  3. Disable the setting “Process during tracking request”. Check you have not setup a cronjob running queuedtracking:process. (We want to make sure the requests in the queue are not processed).
  4. Enable partial maintenance mode by disabling the User Interface but do not disable Matomo Tracking.
  5. Start Matomo upgrade
  6. Finish Matomo upgrade
  7. Disable maintenance mode
  8. Process all requests from the queue into DB to backfill all your data (via the ./console queuedtracking:process console command)
  9. Disable QueuedTracking plugin again
  10. Matomo normal behavior resumes

If you have any feedback or suggestion, please leave a comment below.

I would like to test early beta and RC releases, how do I enable automatic updates to use these development versions?

Login as the Super User in Matomo (Piwik), go to System > General Settings. Next to “When checking for new version of Matomo, always get”, select “The latest beta release”. Click Save at the bottom of the page. You are now using the beta release channel!

To update to the latest beta (or release candidate) version, go to Administration, then click on the “Check for updates” box in the top right of the screen. In this box, click “Check for updates”. If a new beta is available, the “About Matomo” box will turn orange. You can then update Matomo in one click.

We do only release beta versions that are supposed to be stable (when our thousands of automated tests were successful), but please note that beta versions have a risk of containing bugs (which in some very rare cases could lead to data loss). If you find and report a bug in a beta version, we will aim to fix it as quickly as possible.

To manually download any Matomo package version, visit builds.piwik.org.

Thank you so much for using the beta channel!