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
Please see the Matomo (Piwik) Requirements for further information.
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].
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.
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).
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.
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.
Matomo (Piwik) works very well on the webserver Nginx indeed! To get started, check out the contributed nginx server configuration which aims to be fast, secure and flexible. Some features included in this configuration are: Referer and User Agent filtering (disabled by default), using php-cgi, php-fpm or proxying to Apache with mod_php.
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:
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.
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:
Connect to your MySQL database:
Create a database for Matomo:
$ mysql> CREATE DATABASE piwik_db_name_here;
Create a user called
$ mysql> CREATE USER 'piwik'@'localhost' IDENTIFIED BY 'my-strong-password-here';
Grant this user
piwikthe permission to access your
$ mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON piwik_db_name_here.* TO 'piwik'@'localhost';
In these instructions:
piwik_db_name_herewith the name of your MySQL database (if possible, this database should only have the Matomo (Piwik) tables installed).
my-strong-password-hereby a strong secure password.
piwikby your chosen MySQL username (or simply use
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.
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
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)?.
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.
During the Matomo (Piwik) installation at the Database setup step, the host can be specified as:
- IP address
You can specify a custom port number to connect Mysql (instead of default 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
port = 3500 unix_socket = /path/to/sock # if specified, it will override any specified hostname and/or port
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
[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.
- 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
mysqldumpto 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 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.
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
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
To setup SSL connection MySQL in Matomo, you can follow the steps below:
- First, you need to install Matomo over standard insecure non-SSL connections
- Then once Matomo is working, obtain SSL keys and certificate files generated using the same version of openssl as MySQL
- in your config/config.ini.php’s
[database]section, set the
ssl_cato absolute paths to the required files (and make sure PHP can read those files or you’ll get strange MySQL errors)
- Optionally set
ssl_cipherto your desired cipher
- If you’re using a self signed certificate (& your PHP version has a PDO/MySQLi that supports skipping the verification check), set the
- 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
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.
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.
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.phpfile, and under
[database]section change from
type = InnoDBto
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.phpfile and below
[database]add a new line:
type = TokuDB.
- Enjoy your high performance Matomo Analytics (formerly Piwik Analytics) service!
To backup Matomo:
- Regularly backup the Mysql database containing Matomo (Piwik) tables (eg. using an existing Mysql backup script)
- Regularly backup the file
- Regularly backup any Plugin you may have installed from the Marketplace, stored in
To restore a Matomo (Piwik) backup:
- Import the Mysql backup data in a new Mysql database you have created
- Download the latest version of Matomo (Piwik), unzip and upload
- 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.
- 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.
- 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:
- download the font unifont.ttf
- unzip the archive on your computer
- 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