Update Matomo

Update Matomo

This page explains how to update Matomo (Piwik) to the latest version. We hope you will always use the latest version of Matomo and have made upgrading a very easy and safe process. There are two main methods:

The One-Click Matomo Update

You can use the one-click upgrade and update your Matomo in 10 seconds – in just one click of a button!

Step 1: Set Write Permissions on the Matomo folder with FTP

To carry out the one-click update, the Matomo folder needs to have the correct permissions on your web server, to allow Matomo to download the file, extract Matomo and overwrite the existing files.

Please give write permission via your FTP software (CHMOD 0755) to your Matomo root folder. In some cases, the auto update might still not work, try to change the owner of the matomo to your web server user, or temporarily CHMOD 0777.

After the one click update has successfully completed, you may also choose to change back your Matomo folder and files to read only permissions. Important: the tmp/ folder must be writable at all times. Note that if you use the GeoIP auto updater feature, you will also need to make the misc/ folder writable.

Click on the Alert Box in Matomo

Login as a Super User in your Matomo, then go to “Administration”. At the top right, you will see the info box which looks like this:

When a new version of Matomo is available, you’ll be alerted in this box.

Once a new Matomo version is released, the message may take up to 8 hours to appear in the alert box.

Read the Message and Click Update Automatically

Watch the magic!

Treat Yourself

Your Matomo is now updated! Why not share your experience with others by writing a blog post, or spend some time doing new analysis on the Matomo numbers? Have you tried looking at your top websites referrers or sorted by decreasing bounce rate?

Or simply sit back for a few moments and enjoy the beauty of life!

The Manual Three-Step Update

If for some reason the one-click update doesn’t work for you, you can still update Matomo using FTP.

1) Back up your Configuration File

Please back up your Matomo configuration file. You can find this at:

config/config.ini.php

This file contains the details for your existing installation, e.g. your database sign-in information and list of enabled plugins.

2) Replace the Matomo files with the latest version

You can download the latest Matomo release from builds.matomo.org/matomo.zip. After downloading it, you can extract it to your computer.

If you upload these files using FTP to your Matomo server, please make sure all files are transferred in binary mode. It is not needed to delete your old Matomo files before transferring the new ones. The new files should overwrite all the old files with the same names.

If you have SSH access to your server you can download the latest version and extract it directly from the server hosting Matomo:

# go into the the directory that contains your existing "matomo/" installation 
$ wget https://builds.matomo.org/matomo.zip # download latest version
$ unzip -o matomo.zip # extract it to "matomo/" directory
$ rm matomo.zip # delete the archive and read below the next step

3) Update Matomo

Visit your Matomo installation in your web browser. If your new instance of Matomo requires changes to be made to the database, you will see this screen:

This will update your database so that it is compatible with the latest code.

Please be patient: database updates (for example adding a new index) can take a few minutes. Do not close your browser or click refresh during this process. If you fail to carry out this step correctly your Matomo installation may display incorrectly or not work at all.

Database Upgrade for High Traffic Matomo Servers

For high traffic websites, where the update process could take from a few minutes to a few hours, it is highly recommended that you run the database update process in the command line. You can trigger the Matomo update by calling in your shell

$ ./path/to/matomo/console core:update

(If this command does not work, you may try alternatively: php /path/to/matomo/console core:update)

For Medium and High traffic Matomo servers, we also recommend that you turn off Visitor Tracking & turn off the Matomo User Interface while you run the upgrade on the command line. This will ensure that the DB Schema updates are finished as soon as possible and without concurrent read/write errors.

When you put Matomo in maintenance mode, no data will be tracked. There is a way to backfill the tracking requests and not lose any data: learn more in this FAQ.

Need help to update your Matomo to the latest version?

If you are not sure about upgrading Matomo on your own and need help to upgrade your Matomo to the latest version, we can help you. We, the creators of Matomo, offer quality professional support and will help you schedule and smoothly upgrade your Matomo and database. For example when you have a high traffic Matomo server, a very large database, or when you are not sure about the upgrade path, we are here to help and make this process as easy as possible for you.

Troubleshooting

Please visit the Matomo Update FAQ for common questions and answers.