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 (Piwik) 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.

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 Matomo available as one click installation in cPanel, Softaculous, Installatron, Webmin or other tools?

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

Is Matomo compatible with Windows, IIS or Apache, or Microsoft Web Platform Installer?

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.

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

When installing Matomo (Piwik) you need to specify a 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 piwik_db_name_here;
    
  3. Create a user called piwik:

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

    $ mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, FILE ON piwik_db_name_here.* TO 'piwik'@'localhost';
    

In these instructions:

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

Is Matomo compatible with Microsoft SharePoint and provide SharePoint analytics reports?

A dedicated solution called SharePoint Analytics for Matomo (Piwik) exists. It lets you easily integrate Matomo web analytics with your SharePoint service and learn more about the productivity of your employees and overall user engagement. It also supports connecting SharePoint to the Analytics solution using SSO and ADFS. Learn more.

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 (Piwik), 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:

[General]
assume_secure_protocol = 1

If you install Matomo (Piwik) 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:

[General]
; 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 (Piwik) 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).

Note: an alternative solution on Apache 2.4 and Apache 2.5 is to 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 (Piwik) config settings.

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

If you’re using Matomo (Piwik) 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 (Piwik) 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:

 [General]
 ; 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 (Piwik).

You might also be interested in How do I force Matomo (Piwik) login to use SSL (https)?.

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

Matomo (Piwik) team maintains a package and a repository for Debian. It lets you install Matomo in seconds using sudo apt-get install piwik. To get started and be able to run this command, read the Matomo Debian package blog post.

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 (Piwik) 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 (Piwik) to a new domain or subdomain,

  • move all your Matomo (Piwik) 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[] = "example-stats.net"
  • open the new Matomo (Piwik) 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 piwik.example.org and is now installed in example-stats.net, 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 (Piwik) 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.

Often when you want to migrate one or more websites from one Matomo (Piwik) instance to another, the easiest solution is to use the SiteMigration plugin.

In case you want to migrate the complete Matomo (Piwik) service and database to another server, follow these steps:

  • Export your mysql database in a file; you can use tools such as phpmyadmin or mysqldump to do this.
  • Note that if you are not deleting your old visitor logs, then you do not need to backup the piwik_archive_* tables, as they would be automatically re-created and processed from the other piwik tables.
  • Import the backed up database in your new server; you can use phpmyadmin to import the file that you previously created. This should create more than a dozen Matomo (Piwik) tables in your database.
  • Install Matomo (Piwik) 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, “piwik_”). 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 builds.piwik.org server
  • If 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 piwik.example.org and you now installed it in piwik.example-different.com or example.org/piwik, 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.

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.

To use Matomo (Piwik) the recommended way is to download the latest stable version. It is not recommended to use Matomo directly from our Git repository for various reasons:

  • The Matomo (Piwik) 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 (Piwik) to be slower. For example caches might be disabled by default.

Setting up deploying from Git

In case you want to use the very latest bleeding edge Matomo (Piwik) nonetheless and understand the risk, 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 https://github.com/piwik/piwik.git .

# 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 https://getcomposer.org/installer | php 
php composer.phar install --no-dev

# 4) Now install Matomo via the web interface: https://matomo.org/docs/installation/ 

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

Faster cloning

The Matomo (Piwik) 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 https://github.com/piwik/piwik.git

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 (Piwik) 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

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
  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

How do I use the database to store session files, instead of storing sessions in files?

By default, Matomo (Piwik) uses files to store session data. These files are located in the tmp/sessions folder under your Matomo directory. Where file-based session storage may be insecure (e.g., in some shared hosting environments) or where you have to share session data between servers (e.g., load balanced web servers), you can instead use the database to store session data. In config/config.ini.php, under the [General] section (add this section if it doesn’t already exist):

session_save_handler = dbtable

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

Related: Matomo (Piwik) widgets should load very fast as Matomo is designed for speed. If your widgets load slowly, maybe your server runs on slow NFS disks? This setting will make widgets fast again.

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

Matomo (Piwik) only works on Mysql, where all the development and testing is done. Supporting multiple databases is a long term objective for Matomo, but not our current focus. This project will require a lot of testing, coding… and human talent. We call on the community to help us in bringing better technology support to Matomo!

Postgresql: There is a beta non official posgresql port built by a community member, more information about Postgresql Matomo (Piwik) on this ticket. We welcome constructive discussions and pull requests in this area. Please test the fork and report any feedback you have. We want ultimately to merge this fork back in Matomo core.

SQLite: similarly to Postgresql we would love to support SQLite, especially for low traffic websites. Matomo (Piwik) should ideally run anywhere, even on cheap and very small servers, Freedom boxes and USB sticks (in your pocket?). We would like to work with you to support SQLite if you can contribute in some way.

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

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

Nosql: Regarding using Matomo (Piwik) with Nosql databases, we are also considering and listening to user feedback. 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, this would not remove Mysql, but it would maybe allow to scale further.

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 Infinidb are partly compatible with Mysql queries. This could also offer a superb solution to scaling Matomo (Piwik) further.

Summary: Get in touch with the Matomo (Piwik) team if you are interested in working with us in this area. Matomo is an open platform, our long term vision is that Matomo will ultimately run anywhere, or when configured right, that it will handle billions of requests. Stay tuned, let’s hack it.

How do I uninstall Matomo?

To uninstall Matomo (Piwik), follow the following steps:

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

Matomo (Piwik) will then be successfully uninstalled.

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

By default Matomo (Piwik) 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 (Piwik) release to your server
  • Before you install Matomo (Piwik), modify the config/global.ini.php file, and under [database] section change from type = InnoDB to type = TokuDB
  • Install Matomo (Piwik) 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 (Piwik) backup:

  1. Import the Mysql backup data in a new Mysql database you have created
  2. Download the latest version of Matomo (Piwik), 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 (Piwik) 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 piwik/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

Any questions?

Many answers and more information about Matomo you can find here:

We are social

Follow us: