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’re using Matomo for WordPress

You can find the “Matomo version” under Diagnostics: find the system report in Matomo for WordPress.

Latest version of Matomo

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 first section “Export your MySQL/MariaDB database in a file” in our FAQ “How do I backup and restore the Matomo data?”.

How do I restore my MySQL database?

Please see the second section in our FAQ: “Restore the backed up database dump”.

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

or

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

or

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

or

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

or

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? (no Tracking API downtime)

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). Advantage of this method is that it will be able to recover 100% of all tracking requests, while Option 1 (using server access logs) will not be able to recover the POST requests.

Steps to follow:

  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 (set maintenance_mode=1), but it is important to not disable Matomo Tracking (leave the default record_statistics=1).
  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?

To use the beta release channel: 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!

Then you can easily update to the latest beta version (or release candidate): 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.

To manually download any Matomo package versions including betas, visit builds.matomo.org.

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.

Thank you so much for using the beta channel!

How to convert the database to utf8mb4 charset?

As of Matomo 4, the utf8mb4 charset is supported. New installations of Matomo will automatically use this charset if it is available.

This new charset has the advantage that it is able to store 4 bytes characters, such as emojis, less common characters of asian languages, various historic scripts or mathematical symbols.
To prevent errors when inserting such characters in the database Matomo will automatically replace those chars with a � if utf8mb4 is not used.

If you want to convert your database to utfmb4 you can do this with one of this possibilities:

Before doing the update, we recommend creating a database backup, to circumvent any possible loss. As converting the database and its tables might take several hours depending on your database size, tracking might not work correctly in this time. See this FAQ for possible steps on how to update without losing any tracking data.

Convert the Matomo database tables to utf8mb4 using a console command

You can trigger the conversion by using this console command:

./console core:convert-to-utf8mb4

(Note: if the command returns Command "core:convert-to-utf8mb4" is not defined. then your database should already be using utf8mb4 and you don’t need to run the command.)

Convert your Matomo database tables to utf8mb4 using a background task

If you are not able to run a console command there is also a possibility to trigger a conversion as scheduled task in the background. You can enable that in the section Updater settings within Matomo’s General settings.

We do not recommend doing this for bigger instances as you can’t control at which time this will happen.

Convert your Matomo database tables to utf8mb4 manually

If you do not want to use one of the other possibilities for any reason, you can also convert your database manually. Ensure to change the charset of the database and all tables to utf8mb4. We strongly recommend to disable tracking during the conversion of Matomo’s log tables. Once all tables are converted, you need to set the database charset in the Matomo configuration file to utf8mb4 to tell Matomo it can use it. To get a list of all commands and queries you need to execute, you can use the conversion command this way:

./console core:convert-to-utf8mb4 --show