How do I install Matomo?

Read our detailed step-by-step installation guide for complete instructions on how to install Matomo (Piwik). You can also buy a pre-installed Matomo server in a few clicks and for a small fee at Best Matomo service providers

What are the requirements for installing Matomo?

Please see the Matomo (Piwik) Requirements for further information.

Is there a Video that explains how to Install Matomo?

To learn all about what it takes to install Matomo on your web server, please check out this video: How to Install Matomo Analytics (formerly Piwik Analytics) [Video]. Once Matomo is setup, check out the following video to learn about configuring Matomo settings to customize your web analytics platform: How to Setup Matomo Analytics (formerly Piwik Analytics) [Video].

Do I need to create a MySQL database?

Matomo (Piwik) requires access to a MySQL database to store your web analytics data. During the installation process you can specify an existing MySQL database for Matomo to use. If a database cannot be found, Matomo will create one for you.

How do I use Matomo without installing the platform on a server?

When you cannot install Matomo (Piwik) yourself on a server, or if you don’t want to deal with the technical complexities such as keeping software up to date and taking regular backups, we recommend that you use our Matomo Cloud (formerly Piwik Cloud) service. This comes with a 30 day free trial and we make sure you always get to use the latest Matomo. With our cloud, you remain in complete control of your data (100% data ownership!) while respecting your users’ privacy.

Get started now by signing up to Matomo Cloud (formerly Piwik Cloud).

How do I find out which version of PHP I have?

To get information about your server, ask your web hosting company or your sysadmin. You may also use the phpinfo() function, which will give you more information about your Web server and PHP configurations.

Is Matomo Analytics compatible with Amazon AWS, Google Cloud, Azure, Rackspace, Openstack Cloud, Alibaba Cloud?

Absolutely, you can easily setup Matomo Analytics to run on any Cloud platforms out there such as Amazon AWS, Google Cloud, Microsoft Azure Cloud, Openstack Cloud, Alibaba Cloud, Rackspace Cloud and more. To setup Matomo Analytics we recommend you check out the Requirements to run Matomo and then How to install Matomo.

For example you can setup Matomo to use

  • AWS RDS MySQL, AWS RDS Aurora. Note: if you’re on AWS, do not use AWS Aurora Serverless for database, instead use AWS RDS MySQL or AWS RDS Aurora.
  • MySQL Database on Microsoft Azure (PaaS)
  • Cloud SQL for MySQL on Google Cloud
  • any other managed MySQL service

If you are familiar with Docker, you can also use Docker to setup Matomo Analytics on your Cloud provider.

If you need any help, contact our Support team.

My Web host supports PHP4 or PHP<5.3 by default. How do I enable PHP5.3+?

Serious web hosting companies will provide the ability to enable PHP 5.3, either via a config setting in your web host administration panel, or via a .htaccess. If you do not have a server with PHP5 and your web host doesn’t support PHP5, we have partnered with high quality web hosts who provide a pre-loaded Matomo (Piwik) for a small fee.

If your web host supports PHP4 but hasn’t enabled PHP5, it might be possible to enable it manually. Here are the most common ways to enable PHP5; create a .htaccess file in your piwik folder containing

  • version A: AddHandler php5-cgi .php
  • or version B: SetEnv PHP_VER 5
  • or version C: AddType x-mapp-php5 .php
    AddHandler x-mapp-php5 .php

If this does not work, please contact your web host and they should enable the latest PHP version for you.

Do I need to use PHP on my websites to use Matomo?

You will need a server with PHP to run Matomo (Piwik). However, the tracking code is a simple JavaScript tag, which can be added to any webpage written in Python, Jsp, ASP, .NET, etc. For example, the same instance of Matomo can track data from a PHP website, a simple HTML website and a complex JSP application, simply by copy and pasting the JavaScript tag into the desired pages. If you do not have a server with PHP enabled, we have partnered with high quality web hosts who provide a pre-loaded Matomo for a small fee. See the Matomo Cloud (formerly Piwik Cloud) service.

Is Matomo compatible with Nginx?

Matomo (Piwik) works very well on the webserver Nginx indeed! To get started, check out the official nginx server configuration which aims to be fast, secure and flexible. It’s a good starting template for Nginx beginners and a quick way to get started with Matomo for Nginx experts.

Is it possible to use Docker containers to setup and run the Matomo Analytics application?

Yes, we offer Docker Matomo to let you setup the Matomo Analytics application using Docker and containers. Learn more on the Docker Matomo project, and check out the Requirements to run Matomo Analytics.

If you need professional help, contact our Support team.

Is Matomo available as one click installation in cPanel, Softaculous, Webmin or other tools?

Softaculous and Installatron both support Matomo latest versions via their useful One click install services. See:

How do I Install Matomo with Plesk

This guide will show you how to install Matomo via Plesk 18.0.21.

Prerequisites: PHP CLI and PHP MySQL PDO driver (or Mysqli driver) will need to installed and running.


If you already have a website configured you may want to create a subdomain for Matomo to be installed into (e.g, alternatively you can create a folder called for example “matomo” and reference this folder for your installation (e.g This guide explains how to install Matomo using both methods.

  1. Login into your Plesk and choose Websites and domains from the left navigation menu.

  2. Click on the Add subdomain from the buttons above the domains list (for subdomain method)

  3. Create your Matomo subdomain

    In this case we will create If you do not want to create a subdomain simply create a directory within your website.

  4. There are two methods to upload Matomo to Plesk

    a. Using a tool like FileZilla upload the unzipped Matomo download into the subdomain or folder you have created. This method can take a long time to upload all the Matomo files.

    b. (Faster method) Upload the zip file using the file uploader option in Plesk.

    Select the matomo zip file, Plesk will ask for unzip location.

    Click Ok to unzip Matomo. This can take some time depending on the performance of your web server.

  5. Once the files have been uploaded or unzipped, browse to your subdomain or folder containing the installation. This could be in this example, or if you have installed Matomo in a folder.

  6. The installation procedure for Matomo will begin.

    Check all the requirements are met for your installation.

  7. If all the requirements have been met, the next step is to create the Matomo database user and database. In Plesk, choose Databases from the left navigation menu. Then select Add database.

  8. Create the database and user for the database.

    Take note of the database server hostname, the database name, the database username and password: these details will be required during the installation.

  9. Confirm the user has all the privileges required to access the database.

  10. Return to the Matomo installation and enter the database details created in the above step.

  11. The tables will be created in the database. Confirm this has been successful.

  12. Complete the rest of the installation.

Configuring the archiving

Now that the installation is complete, we will set up a scheduled task (cronjob) to trigger Matomo archiving

  1. Select Tools and Settings from the left-hand navigation menu.
  2. Select Scheduled task (Cron jobs) from the Tools and Resources menu.
  3. Select Add task
  4. Select Run a command.
  5. Enter the following command in the Command field, edit the command to match your needs first.
    /opt/plesk/php/8.1/bin/php /var/www/vhosts/ core:archive --no-ansi >> /var/www/vhosts/
    The path typically for Plesk will be /var/www/vhosts/domain. If you are on shared hosting, please check with your hosting company. The path to the cron-matomo-archive.log file can be to a folder of your choice (for example in /var/www/)
  6. Set the frequency to “Run Hourly” as we want the cron to run every hour.
  7. Set “Notify” to “Every time”.
  8. Select Run Now and confirm the cron job is running successfully. Click ok to save the cron job, the cron job should now be listed in the configured cron jobs.

Disable Web Application Firewall (ModSecurity)

If you have enabled Web Application Firewall (ModSecurity) in Plesk, you will need to disable it for your Matomo domain:

  1. In Plesk, in the left sidebar, click Websites & Domains.
  2. Select the Matomo domain, and then click Web Application Firewall.
  3. In the Web application firewall mode section, click Off
  4. Click OK. Plesk will disable the Web Application Firewall for your Matomo domain.

Congratulations, you have successfully installed Matomo Analytics through your Plesk!

Install the JavaScript Tracking code in your website

The next step is to include the Matomo Tracking Code in your websites to start tracking your website and app users.

Happy Analytics!

Is Matomo compatible with Windows, IIS, Apache, or Nginx?

Matomo (Piwik) is supported by Windows using IIS or Apache or Nginx, and also supported on Linux and Mac. See the requirements to run Matomo.

For detailed steps on getting Matomo setup on Windows, please see our dedicated Matomo on Windows FAQs

How do I create a new database and database user in MySQL?

When installing Matomo you need to specify a MySQL (or MariaDB) database hostname, user and password.

To create your database and database user, you would typically use your web hosting provider interface which would let you add a new MySQL database and create a new user with permission to access this database, in just a few clicks.

If you are installing Matomo (Piwik) on your own server and/or don’t have a tool available to manage your database, you can manually create the MySQL database user by following these steps:

  1. Connect to your MySQL database:

    $ mysql
  2. Create a database for Matomo:

    $ mysql> CREATE DATABASE matomo_db_name_here;
  3. Create a user called matomo, if you are using MySQL 5.7 or MySQL 8 or newer:

    $ mysql> CREATE USER 'matomo'@'localhost' IDENTIFIED WITH mysql_native_password BY 'my-strong-password-here';

    Or if you are using an older version such as MySQL 5.1, MySQL 5.5, MySQL 5.6:

    $ mysql> CREATE USER 'matomo'@'localhost' IDENTIFIED BY 'my-strong-password-here';
  4. Grant this user matomo the permission to access your matomo_db_name_here database


    It is important to grant the user the following privileges: SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES

  5. (OPTIONAL) Grant this user matomo the FILE global privilege: (if enabled, reports will be archived faster thanks to the LOAD DATA INFILE feature)

    $ mysql> GRANT FILE ON *.* TO 'matomo'@'localhost';

In these instructions:

  • replace matomo_db_name_here with the name of your MySQL database (if possible, this database should only have the Matomo tables installed).
  • replace my-strong-password-here by a strong secure password.
  • replace matomo by your chosen MySQL username (or simply use matomo).

How do I configure Matomo when the server is installed behind a proxy?

This FAQ details the few different use cases and configurations when using a proxy in Matomo (Piwik).

If Matomo is behind a reverse proxy

If you install Matomo, connecting through a reverse proxy (https-to-http), the following line should be automatically added to your config/config.ini.php file during the Matomo installation:

assume_secure_protocol = 1

It is highly recommended that when you configure this setting, you also add force_ssl:

force_ssl = 1                 ;please add this as well
assume_secure_protocol = 1    ;if you add this

It will ensure your emails are sent with https:// links as well as ensure all other secure content settings related to SSL (https://) work as expected.
In particular, all http:// links will be redirected to https://. See Force Matomo to use SSL for more information.

If you install Matomo from behind the reverse proxy (where Matomo can’t detect https will be used), you should set the above manually. Also, depending on your proxy server, the Visitor IP is set in a different HTTP Header which should also be automatically detected on install and added to your config/config.ini.php:

; Uncomment line below if you use a standard proxy
;proxy_client_headers[] = HTTP_X_FORWARDED_FOR
;proxy_host_headers[] = HTTP_X_FORWARDED_HOST

; Uncomment line below if you use CloudFlare
;proxy_client_headers[] = HTTP_CF_CONNECTING_IP

; Uncomment line below if you use another proxy (that sets Client-IP header)
;proxy_client_headers[] = HTTP_CLIENT_IP

If Matomo was unable to detect your proxy configuration, you may add these lines manually in your Matomo config.ini.php file (remove the leading “;” character to enable the setting).

Be aware that PHP applies some transforms to headers: uppercases them, prefixes HTTP_ and converts dashes to underscores. So if your reverse proxy is sending X-Forwarded-For, it should be entered in the config as HTTP_X_FORWARDED_FOR.

It is also possible to check multiple proxy_client_headers, which will be checked in order until a header value is found. For example, with the config below:

proxy_client_headers[] = HTTP_WAF_FORWARDED_FOR
proxy_client_headers[] = HTTP_LB_FORWARDED_FOR
proxy_client_headers[] = HTTP_X_FORWARDED_FOR

This means first try the HTTP_WAF_FORWARDED_FOR header and if that doesn’t exist, then try the HTTP_LB_FORWARDED_FOR and if neither exists then finally try HTTP_X_FORWARDED_FOR. The array[] syntax is shorthand in PHP for array_push so adds to the existing array.

You can exclude internal IPs (e.g. LoadBalancer IPs) from being used from these headers using the proxy_ips[] config to exclude certain ranges of IP addresses. For example the following config will ignore commonly used internal IP address ranges:

proxy_ips[] = 192.168.*.*/16
proxy_ips[] = 10.40.*.*/16

It is also possible to debug this to list the exact details in the Matomo log file.

Security consideration

By default, Matomo follows the RFC7239 implementation and always reads the first IP from a proxy header. Depending on your set up, for security reasons you may prefer to read the last IP instead by setting below configuration. This way you ensure that a user can’t set for example a custom X-Forwarded-For header in the client to fake an IP address. This way they could otherwise pretend to have an IP from your organisation by simply adding a header to any request and work around specific allow or deny lists of IP addresses for example.

proxy_ip_read_last_in_list = 1

This feature requires Matomo 4.4 or newer.


  • If your server runs IIS reverse proxy, HTTP_X_FORWARDED_HOST needs to be added manually to “Allowed Server Variables” and added to the inbound rewrite rule and set to {HTTP_HOST} so that it passes through the original HTTP_HOST value provided by the client to Matomo. Learn more.

  • If you use Apache 2.4 or Apache 2.5, there is an alternative solution, you could use mod_remoteip to override the client IP with the IP as provided by a proxy or load balancer. Then you won’t need to specify these Matomo config settings.

If Matomo is behind a reverse proxy and installed in a sub-path

If you’re using Matomo behind a reverse proxy with a different path such as rewrite ^/piwik/(.*)$ /$1 break; (in nginx.conf when Matomo is installed in the /piwik path), you would need to:

1) configure your web server to provide a header HTTP_X_FORWARDED_URI. For example on NGINX, when Matomo is installed in /piwik path, you would set proxy_set_header X-Forwarded-Uri /piwik; in your nginx.conf.
2) configure Matomo to read this HTTP_X_FORWARDED_URI to construct correct URLs. In Matomo config/config.ini.php in the [General] section add:

 ; Use the header HTTP_X_FORWARDED_URI to construct the current script name
 proxy_uri_header = 1

Matomo is behind an outgoing proxy

If your server is configured behind an outgoing proxy, check out this FAQ: outgoing Proxy easy setup in Matomo.

You might also be interested in…

How do I install Matomo on Debian GNU/Linux servers?

To install Matomo on Debian systems such as Ubuntu, MX Linux, Linux Mint, Deepin, AntiX, PureOS, Kali Linux, Parrot OS, Devuan, Knoppix, etc. you will need to manually check that:

  1. your system can meet the requirements
  2. then proceed to install Matomo by following the instructions in our Matomo Installation Guide.

How do I specify to use Mysql on a custom port or to connect Mysql over a socket?

During the Matomo (Piwik) installation at the Database setup step, the host can be specified as:

  • hostname
  • IP address

You can specify a custom port number to connect Mysql (instead of default port 3306):

  • hostname:port
  • ipaddress:port

You can also specify to connect through a socket:

  • /sock/path – anything before the slash is ignored
  • localhost – localhost has a special meaning in php 5.3+; with mysqlnd, it means use the default sock path

If you have already installed Matomo you can configure the port or socket in the config.ini.php file below your [database] section:

 port = 3500
 unix_socket = /path/to/sock # if specified, it will override any specified hostname and/or port

How can I reinstall Matomo? Can I keep the existing data?

To force a new installation of Matomo (Piwik), you can simply delete the configuration file in config/config.ini.php. When you visit Matomo, it will trigger the Matomo installation process. If you install Matomo specifying an existing database containing Matomo data, the installation process will automatically detect that the Matomo tables already exist. You will be able to choose to either keep your existing data, or delete the tables and start from a clean database.

I want to migrate Matomo and move it to a new domain or a new subdomain URL, with the same MySQL server. How should I proceed?

To move Matomo to a new domain or subdomain,

  • move all your Matomo files to the new directory, on your new domain or subdomain.
  • in your config/config.ini.php file, below [General] section, add a line with your new host: trusted_hosts[] = ""
  • delete the folder tmp/ within your new Matomo directory.
  • open the new Matomo URL in your browser, and check that Matomo works as expected.
  • since the Matomo (Piwik) domain name has changed, you also need to change the Matomo JavaScript tags on all your tracked pages. For example, if Matomo was installed in and is now installed in, you need to update the tags on all your websites’ pages to point to the new URL.
  • If you use the auto archiving cron, you may have to update or setup the script path in your crontab file.

If you want to reinstall Matomo please see How can I reinstall Matomo? Can I keep the existing data?

How can I move Matomo from one server to another, also migrating the data from one mysql server to another?

To move Matomo (Piwik) from one server to another, you need to move all the Matomo files (the whole directory containing Matomo files), as well as the database to another MySQL server.

Follow these steps to migrate all Matomo service and data to another server

  • Export your mysql database in a file; you can use tools such as phpMyAdmin or mysqldump to do this. The simplest way to make a full copy of the MySQL database is to run the mysqldump command with this set of parameters:
    $ time mysqldump --extended-insert --no-autocommit --quick --single-transaction MATOMO_DATABASE_NAME -uMATOMO_DATABASE_USERNAME -p > matomo_backup_database.sql
    (If you use Matomo Cloud, then you can securely download your full database dump by contacting the Matomo Cloud Support team.)
  • We can then compress this backup before sending it to the backup server:
    $ tar zcf matomo-mysql-database-$(date +%Y-%m-%d-%H.%M.%S).sql.tar.gz matomo_backup_database.sql
  • Import the backed up database in your new server; you can use phpmyadmin to import the file that you previously created, or restore the DB backup by running the following command:
    $ time mysql MATOMO_DATABASE_NAME -uMATOMO_DATABASE_USERNAME -p < matomo_backup_database.sql. This should create more than a dozen Matomo tables in your database.
  • Install Matomo in your new server; it is important that you install the exact same version as the one you are currently using. During the installation process, you will be asked to provide the mysql server, login, password and table prefix. Specify the same table prefix (by default, “matomo_”). Matomo will detect that the tables are present in the database and all your existing websites and reports will be automatically detected. It will only work if you re-install the exact same version – see Which version of Matomo I use?, and download the right version from the server
  • If the Matomo domain name has changed, you also need to change the Matomo javascript tags on all your tracked pages. For example, if Matomo was installed in and you now installed it in or, you need to update the tags on all your websites’ pages.
  • If you use the auto archiving cron, you will have to setup the cron script on the new server.

Note that during the operation, visits will not be tracked.

See also: How do I migrate a particular website in Matomo to a different Matomo installation?

How do I use Matomo from the official Git repository?

Matomo (Piwik) is a free/libre software project, and the source code is freely available on our Git repository.

It is not recommended to deploy Matomo in production directly from our Git repository for various reasons

To deploy and use Matomo the best practise and recommended way is to download the latest stable version.

It is not recommended to deploy Matomo in production directly from our Git repository for various reasons:

  • The Matomo version from Git contains files that are only needed for development. Those files are not needed in production and could potentially cause harm, for example our test files.
  • Some default settings are different which can cause Matomo to be slower. For example caches might be disabled by default.
  • Deploying from Git into production can have serious security implications.

If you deploy from git, make sure that the .git directory in the web root cannot be accessed directly. For example

For example when using Apache a redirect like this can prevent accessing these files:

RedirectMatch 404 /\\.git(/.*|$)

Setting up deploying from Git

In case you want to use the very latest bleeding edge Matomo nonetheless and understand the risks, you may use Matomo directly from our Git repository. To deploy Matomo from Git, run the following commands once:

cd path/to/piwik

# 1) Clone the Git repository 
git clone .

# 2) Optional step when you want to deploy a particular stable release (eg. 2.15.0) and not use bleeding edge
git checkout 2.16.3
git submodule update --init --recursive

# 3) Setup composer libraries
curl -sS | php 
php composer.phar install --no-dev

# 4) Now install Matomo via the web interface: 

# 5) Disable Matomo development mode
./console development:disable

Faster cloning

The Matomo repository is using Git LFS for all screenshots it contains for visual regression testing. This may cause the git clone to take a long time. If you are not using Matomo for development you can improve the time to clone the repository by setting an option to disable Git LFS:

git clone --config filter.lfs.smudge=true

Deploying new versions from Git

Continuously deploying the bleeding edge code

To automatically deploy the latest bleeding edge code from our repository, setup a crontab or automated script with the following commands:

cd path/to/piwik

# Checkout piwik.js in case it was changed
git checkout -- piwik.js

# Pull the latest code from Matomo repositories
php console git:pull

# Upgrade the libraries in case there is any to be upgraded
php composer.phar self-update > /dev/null
php composer.phar install --no-dev > /dev/null

# Run the upgrade in case there was one
php console core:update --yes > /dev/null

# Re-generate the piwik.js 
php console custom-piwik-js:update > /dev/null

(Note: we do not recommend to do this on production server, as the latest code from Git may be unstable at times and could cause data loss.)

Deploying a specific release

Alternatively, to deploy a particular Matomo release (in this example 3.0.0), run the following commands:

cd path/to/piwik
git checkout 3.0.0
git submodule update --init --recursive
php composer.phar install --no-dev

Deploying Matomo in production correctly

When it is time to deploy To deploy Matomo in your production environment, download the latest stable version and install Matomo on your server (do not deploy from any Git repository in production!).

How do I setup Matomo to securely connect to the database using MySQL SSL?

To setup SSL connection MySQL in Matomo, you can follow the steps below:

  1. First, you need to install Matomo over standard insecure non-SSL connections. If your MySQL server requires SSL connections, then you can’t install Matomo through the UI, so you will need to disable SSL temporarily while you install Matomo, and then re-enable SSL in MySQL after you installed Matomo.
  2. Then once Matomo is working, obtain SSL keys and certificate files generated using the same version of openssl as MySQL
  3. in your config/config.ini.php’s [database] section, set the ssl_cert, ssl_key, ssl_ca to absolute paths to the required files (and make sure PHP can read those files or you’ll get strange MySQL errors)
  4. Optionally set ssl_cipher to your desired cipher
  5. If you’re using a self signed certificate (& your PHP version has a PDO/MySQLi that supports skipping the verification check), set the ssl_no_verify option to 1.
  6. Verify in the Matomo (Piwik) system check that you are using an SSL connection to the database. You may also want to change your database password.

For example when using AWS RDS, here is an example configuration (where rds-combined-ca-bundle.pem is downloaded from here):

; Database SSL Options START
; Turn on or off SSL connection to database, possible values for enable_ssl: 1 or 0
enable_ssl = 1
; Direct path to server CA file, CA bundle supported (required for ssl connection)
ssl_ca = "/etc/mysql-certs/rds-combined-ca-bundle.pem"
; Direct path to client cert file (optional)
ssl_cert =
; Direct path to client key file (optional)
ssl_key =
; Direct path to CA cert files directory (optional)
ssl_ca_path =
; List of one or more ciphers for SSL encryption, in OpenSSL format (optional)
ssl_cipher =
; Database SSL Options END

Is Matomo compatible with Microsoft SharePoint Online (O365 Analytics) and/or SharePoint On-Premises farms?

Yes you can use Matomo Analytics for your SharePoint sites and learn more about the productivity of your employees and overall user engagement.

Important note: The links below contain information and resources that are neither maintained nor endorsed by the Matomo Team. The use of third party extensions is at your own risk.

1) If you’re using SharePoint Modern experience (SharePoint Online – Office 365, or SharePoint Server 2019)…

The modern experience is designed to be compelling, flexible, mobile, and easier to use. It is available in SharePoint Online in Office 365. Some modern experiences are available with SharePoint Server 2019 (On-Premise).

To measure your SharePoint Modern sites with Matomo, follow the steps explained in this third party article: Setup Matomo Analytics to track Modern SharePoint. The solution involves installing this SharePoint extension using either Powershell or a Bash script. All details are in the article.

2) If you’re using Classic SharePoint sites…

To measure your SharePoint Classic site collections with Matomo, follow the steps in this article: Setup Matomo Analytics to the classic SharePoint site collections. The solution involves running this Powershell script that will automatically add the Matomo Tracking code to your pages.

3) If the above solutions don’t work…

If the solutions above don’t work, we recommend to leave a comment in the comments of the articles that are linked to.

If you’re using older versions of SharePoint On-Premise such as SharePoint 2013 farm, you can try follow this (usually not recommended) solution to include Matomo JavaScript Tracking code in your SharePoint 2013 (intranet) Sites. The solution involves adding the Matomo JavaScript tracking code to your Master pages in SharePoint 2013.

a) Get the tracking code for your website

  • log in to Matomo (Piwik) with your admin or Super User account
  • click on your username in the top right menu, and click Settings to access the administration area
  • click on Tracking Code in the left menu
  • Copy the Tracking code

The tracking code looks as follows:

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq || [];
  (function() {
    var u="//{$MATOMO_URL}/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', {$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=u+'matomo.js'; s.parentNode.insertBefore(g,s);
<!-- End Matomo Code -->

In your tracking code, {$MATOMO_URL} would be replaced by your Matomo URL and {$IDSITE} would be replaced by the idsite of the website you are tracking in Matomo.

b) Add this Tracking code to SharePoint master page.

  • Edit your master page in ‘Advanced mode’ with SharePoint designer 2013
  • and paste/insert the Matomo Tracking code just before </head> tag.
  • Save-Check-in-publish/Approve the master page.

c) Check your Visitors data in Matomo

Under Visitors > Visits Log, select “Today” in the calendar, you can now see your visitors and interactions tracked in real-time.

Using Matomo Tag Manager with SharePoint

See our FAQ How do I use the Matomo Tag Manager with SharePoint?

How do I use the database to store session files?

Matomo since version 3.7.0 will always store sessions in the database.

If you have many concurrent dashboard users, you may need to increase the max number of client connections to the database server.

How do I insert the Matomo JavaScript Tracking code in my SharePoint On-Premises 2013 Intranet Sites?

-> If you are using a recent SharePoint Online or SharePoint On-Premises, please check our other FAQ: Matomo for the new SharePoint

How do I use another database like Postgresql, SQLite, Oracle? Will you support Nosql databases like Hadoop, Mongodb?

Matomo (Piwik) only works on Mysql and MariaDB, where all the development and testing is done.

Supporting multiple databases was a long term objective for us, but we have found that this project would require a huge amount of coding, testing, and ongoing complex support… As a small team we need to stay focused and unfortunately we are not planning to add support for other databases in the future (unless for those that are compatible with MySQL/MariaDB). Also over the years we found that Matomo on MariaDB/MySQL can track up to a few billions of hits per month so the platform scales really well as is.

MariaDB: Matomo is already fully compatible with MariaDB and other Mysql compatible databases. Feel free to use them with Matomo!

TokuDB: You can use Matomo with TokuDB which may help if you manage a high traffic Matomo service. Learn more in the TokuDB FAQ

Nosql: Regarding using Matomo with Nosql databases, we have considered this technology, and our current understanding is that Nosql would have to be implemented in a hybrid way, where Nosql would be used for visitor logs and events, but not for websites, users, reports, and other features. Using Mongodb, Hadoop, etc. would not remove Mysql, but it would maybe allow to scale further in some cases.

Column storage databases: As well as Nosql, and possibly a better approach are the ‘Column storage databases’. This is a technology especially tailored to analytics workload. Some solutions are GPL such as Clickhouse are partly compatible with Mysql queries. This could also offer a superb solution to scaling Matomo further.

PostgreSQL: PostgreSQL has long been a popular feature request, see the ticket for more details. But considering the engineering effort to support PostgreSQL it’s unlikely to happen.

SQLite: supporting SQLite would be helpful for low traffic websites. But we found that it’s already possible to run a MariaDB or MySQL server on most devices and even on cheap and very small servers, such as Freedom boxes, USB sticks-based solutions, and Raspberry Pi.

How do I uninstall Matomo?

To uninstall Matomo, follow the following steps:

  • Remove the Matomo Tracking code from all websites previously tracked with Matomo
  • Delete all Matomo files in the matomo/ folder. In some configurations, the matomo/ folder cannot be deleted using FTP. If you can’t delete the matomo/ folder in your FTP, download the script uninstall-delete-matomo-directory.php, upload it to your server above the matomo/ folder, and execute it in your browser. It will delete the matomo/ folder.
  • Using a Mysql client such as phpMyAdmin or cPanel, delete the Database storing all Matomo tables.

Matomo will then be successfully uninstalled.

Alternatively, you may also want to migrate to Matomo Cloud-hosted instead (contact us for more information).

How do I configure a reader / slave database in Matomo?

You can configure a reader or slave database in Matomo by editing your config file in config/config.ini.php and configuring the reader like this:

host =
username = example_user
password = example_password
dbname = example_db_name
port = 3306
aurora_readonly_read_committed = 0

For this to work, you first need to setup database replication in your MySQL or MariaDB database.

We recommend to only configure a reader if you can ensure there is a minimal replication lag / delay on the reader. Otherwise you might get corrupt/outdated data in the reports.

If configured, the following queries will be executed on the reader (slave) instead of the writer (master):

  • archiving queries that hit a log table
  • live queries that hit a log table

Please note that when you are configuring a reader and are using custom plugins that add new reports (that have a custom archiver), these plugins need to make sure to make use of the reader as otherwise queries will fail. All plugins from Matomo / InnoCraft are compatible. Most third party plugins are automatically compatible as well.

If you are using Amazon Aurora you can enable aurora_read_only_read_committed to prevent purge lag which happens when internal garbage collection is blocked by long-running archiving queries. The setting will be only applied if you have configured a reader database.

How do I install Matomo using TokuDB table engine in a Mysql or MariaDB database?

By default Matomo creates tables in your Mysql database with InnoDB table engine. Sometimes if you manage a high traffic Matomo instance you may want to use Matomo with TokuDB table engine instead of InnoDB. Currently Matomo does not let the user select TokuDB during the installation process. However you can follow these simple steps to install Matomo with TokuDB:

  • Upload the latest Matomo release to your server
  • Before you install Matomo, modify the config/global.ini.php file, and under [database] section change from type = InnoDB to type = TokuDB
  • Install Matomo by going through the few steps. Matomo will create your tables with the TokuDB engine.
  • After the installation is successful, edit on your server the config/config.ini.php file and below [database] add a new line: type = TokuDB.
  • Enjoy your high performance Matomo Analytics (formerly Piwik Analytics) service!

How do I backup Matomo data and files?

To backup Matomo:

  1. Regularly backup the Mysql database containing Matomo (Piwik) tables (eg. using an existing Mysql backup script)
  2. Regularly backup the file piwik/config/config.ini.php
  3. Regularly backup any Plugin you may have installed from the Marketplace, stored in piwik/plugins/* folder

To restore a Matomo backup:

  1. Import the Mysql backup data in a new Mysql database you have created
  2. Download the latest version of Matomo, unzip and upload
  3. Copy the file config.ini.php from the backup into your new piwik setup. You might have to edit the database connection settings in the file if they have changed.
  4. Copy any Third party Plugin installed from the Marketplace from the backup (or download from the marketplace the latest version of these plugins) and copy them into your new piwik setup.
  5. Visit Matomo and check that everything is working correctly!

How do I enable unicode characters (Japanese, Chinese, Russian, Hebrew, Arabic, etc.) in graphs in PDF/HTML reports and Matomo Mobile graphs?

Static image graphs in the PDF/HTML reports and Matomo Mobile app will display standard non unicode characters by default. However if you use Matomo (Piwik) in languages using unicode characters (Hebrew, Arabic, Japanese, Chinese, etc.), please follow the steps below:

  1. download the font unifont.ttf
  2. unzip the archive on your computer
  3. upload the file unifont.ttf in path-to-matomo/plugins/ImageGraph/fonts/unifont.ttf

Graphs in the Mobile app and Scheduled reports should now display all characters properly.

Note: the unifont.ttf will only be used for a set of languages (Japanese, Chinese, etc.). If you wish to use the font for all languages, upload the file unifont.ttf to: piwik/plugins/ImageGraph/fonts/tahoma.ttf overwriting the existing tahoma.ttf

Will Matomo Analytics measure visitors from China on my websites and bypass the Great Firewall?

The Great Firewall of China (GFW) is the combination of legislative actions and technologies enforced by the People’s Republic of China to regulate the Internet domestically. Its role in Internet censorship in China is to block access to selected foreign websites and to slow down cross-border internet traffic.

Google Analytics blocked and slowing down websites in China

Many popular foreign tools such as Google search, Facebook, Twitter, Wikipedia, etc. are blocked and inaccessible in China. Google Analytics is also mostly blocked or quite slow in China. Although many chinese websites use GA, they do encounter data loss (at least 50% of visitors and pageviews are missed), performance issues (website slowing down for foreign visitors and latency increasing).

Using Matomo Analytics to bypass the Great Firewall of China

To bypass the Great Firewall on China and track all visitors from China accurately (or track all visitors to a .cn chinese website), the ideal solution is to use Matomo Analytics. If your Matomo runs on a Chinese server, it will be behind the great firewall and therefore will track all users for sure (chinese users and those outside the country). But even if you run Matomo on your own servers for example in Europe or anywhere in the world (or using the Cloud-hosted Matomo), you will also be able to track Chinese users because your Matomo URL won’t be affected by the Great Firewall. So when using Matomo Analytics, you will get accurate web analytics tracking independently of where your Matomo servers are located.

Learn more about using Matomo On-Premise.