How do I upgrade an installed plugin?

For Matomo On-Premise users, manually updating plugins instead of using the web interface can help avoid potential issues such as browser timeouts during database updates, uneven upgrades across multiple servers, or complications with containerised environments.

If you use any premium plugins (e.g. Heatmaps, Custom Reports, Users Flow), the best practice is to update the entire Matomo codebase, including all plugins, at the same time. Refer to the Matomo Update Guide for detailed instructions..

The recommended steps below will explain how to update a plugin manually. It is best to perform this process during a maintenance window when the Matomo UI is disabled.

1. Required

The following steps will require you to have SSH access to your server’s command line (CLI).

Check plugin compatibility
Before updating, confirm that the plugin version is compatible with your Matomo version. You can find compatibility information on the Matomo Marketplace. For example, the Activity Log plugin page lists its version requirements.

Take Matomo offline
To reduce risk during updates, consider disabling access to your Matomo server. See [this FAQ] for guidance on taking your server offline safely.

3. Download the updated Plugin

Where to download Free Plugins
If you are upgrading a free plugin, download the latest plugin version as a ZIP file from the Matomo Marketplace (published by Matomo or from the repository of the plugin author). Not sure if your plugin is free? Generally, the plugin is free if it does not have an orange-colored download button at the Marketplace link, above.

Where to download Premium (Paid Subscription) Plugins
If you are upgrading a premium plugin, either:

4. Replace the plugin code

  1. Fully delete the existing plugin files before installing the new version.
    For example, before uploading the newest code for HeatmapSessionRecording you should recursively delete everything in the /var/www/html/matomo/plugins/HeatmapSessionRecording directory (your path may vary).
    This prevents file conflicts or leftover code. Those will show up after you complete your upgrade in error messages that resemble “cannot find file xyz”. Don’t feel anxious about deleting the plugin code: most plugin data is stored in the database, not in code, so deletion will not affect your data.

  2. Manually move the files for the new plugin folder into the .../plugins/ directory in your Matomo installation.

5. Permissions, et cetera

It is important for the newer files to have the same permissions, owner, (and context if you are running Red Hat) as your older plugins files.

As an example, we will consider how to configure the files for a plugin: Heatmaps and Session Recordings. Adapt this example to use the name of your plugin and your exact path.

  • Observe the owners and permissions of the files and directories.
ls -l /var/www/html/matomo/plugins/

ls -l /var/www/html/matomo/plugins/HeatmapSessionRecording  # Use the name of your plugin
  • Fix the owner so it matches what Linux considers to be the “name” of your server when your server executes code (Commonly a server will execute commands as either www-data or apache).
sudo chown -R www-data:www-data /var/www/html/matomo/plugins/HeatmapSessionRecording/
  • Fix the permissions of the files and directories:
sudo find /var/www/html/matomo/plugins/ -type f -exec chmod 644 {} \;

sudo find /var/www/html/matomo/plugins/ -type d -exec chmod 755 {} \;
  • Confirm that your plugins all have the same owner and permissions:
ls -l /var/www/html/matomo/plugins/

Alternative to steps 4 and 5

Steps 4 and 5 are a lot of work. To save time, you can replace Steps 4 and 5 by using our installer script to fetch and install the latest versions of all plugins and the Matomo core at once.

6. Activate the updated plugin

  1. Run the following command to clear cached files: php ./console cache:clear
  2. Use the console to activate the plugin: console plugin:activate <PluginName>
  3. After replacing plugin files, run the database upgrade using the following console command in the Matomo root folder: ./console core:update
  4. This will take between several minutes and several hours to complete because it is adding necessary columns to the database.
  5. Open your Matomo interface in the browser and confirm that it is working.
  6. Going forward, we recommend that you prevent anyone from triggering an update by pushing buttons in the browser interface of Matomo. Disable the update of plugins from the Matomo user interface by editing the file …/matomo/config/config.ini.php to include enable_plugins_admin = 0

Multi-server setups

If you’re running Matomo on multiple servers, ensure the updated codebase is deployed consistently across all servers. All plugin and core files must be synchronised to maintain functionality.

Learn more on how to keep the config file and tracker JS files in sync and how to activate a new plugin in a multi-server environment.

Previous FAQ: How do I install a new plugin?