How do I install Piwik?

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

What are the requirements for installing Piwik?

Please see the Piwik Requirements for further information.

Is there a Video that explains how to Install Piwik?

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

Do I need to create a MySQL database?

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 Piwik to use. If a database cannot be found, Piwik will create one for you.

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

When you cannot install 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 Piwik Cloud service. This comes with a 30 day free trial and we make sure you always get to use the latest Piwik. 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 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 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 Piwik?

You will need a server with PHP to run 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 Piwik 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 Piwik for a small fee. See the Piwik Cloud service.

Is Piwik compatible with Nginx?

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

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

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

Piwik is supported by Windows using IIS or Apache, and also supported on Linux and Mac. There is also a one click installation of Piwik under Windows when using the Windows Platform Installer, see the Web App Gallery blog post for more details.

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

When installing 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 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:

    $ sudo mysql
  2. Create a database for Piwik:

    $ 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


In these instructions:

  • replace piwik_db_name_here with the name of your MySQL database (if possible, this database should only have the 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 Piwik compatible with Microsoft SharePoint and provide SharePoint analytics reports?

A dedicated solution called SharePoint Analytics for Piwik exists. It lets you easily integrate Piwik 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 Piwik when the server is installed behind a proxy?

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

If Piwik is behind a reverse proxy

If you install 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 Piwik installation:

assume_secure_protocol = 1

If you install Piwik from behind the reverse proxy (where Piwik 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 Piwik was unable to detect your proxy configuration, you may add these lines manually in your Piwik 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 Piwik config settings.

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

If you’re using Piwik behind a reverse proxy with a different path such as rewrite ^/piwik/(.*)$ /$1 break; (in nginx.conf when Piwik 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 Piwik is installed in /piwik path, you would set proxy_set_header X-Forwarded-Uri /piwik; in your nginx.conf.
2) configure Piwik to read this HTTP_X_FORWARDED_URI to construct correct URLs. In Piwik config/config.ini.php in the [General] section add:

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

Piwik is behind an outgoing proxy

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

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

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

Piwik team maintains a package and a repository for Debian. It lets you install Piwik in seconds using sudo apt-get install piwik.

Read the Piwik Debian package blog post to get started.

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

During the 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 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 Piwik? Can I keep the existing data?

To force a new installation of Piwik, you can simply delete the configuration file in config/config.ini.php. When you visit Piwik, it will trigger the Piwik installation process. If you install Piwik specifying an existing database containing Piwik data, the installation process will automatically detect that the Piwik 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 Piwik and move it to a new domain or a new subdomain URL, with the same MySQL server. How should I proceed?

To move Piwik to a new domain or subdomain,

  • move all your 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[] = ""
  • open the new Piwik URL in your browser, and check that Piwik works as expected.
  • since the Piwik domain name has changed, you also need to change the Piwik JavaScript tags on all your tracked pages. For example, if Piwik 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 Piwik please see How can I reinstall Piwik? Can I keep the existing data?

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

To move Piwik from one server to another, you need to move the php files, as well as the database to another MySQL server.

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

In case you want to migrate the complete 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 Piwik tables in your database.
  • Install 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_”). Piwik 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 Piwik I use?, and download the right version from the server
  • If the Piwik domain name has changed, you also need to change the Piwik javascript tags on all your tracked pages. For example, if Piwik 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.

How do I use Piwik from the official Git repository?

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

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

  • The 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 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 Piwik nonetheless and understand the risk, you may use Piwik directly from our Git repository. To deploy Piwik 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 Piwik via the web interface: 

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

Faster cloning

The 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 Piwik 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 Piwik 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 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 use the database to store session files, instead of storing sessions in files?

By default, Piwik uses files to store session data. These files are located in the tmp/sessions folder under your Piwik 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: Piwik widgets should load very fast as Piwik 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?

Piwik only works on Mysql, where all the development and testing is done. Supporting multiple databases is a long term objective for Piwik, 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 Piwik!

Postgresql: There is a beta non official posgresql port built by a community member, more information about Postgresql 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 Piwik core.

SQLite: similarly to Postgresql we would love to support SQLite, especially for low traffic websites. 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: Piwik is already fully compatible with MariaDB and other Mysql compatible databases. Feel free to use them with Piwik!

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

Nosql: Regarding using 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 Piwik further.

Summary: Get in touch with the Piwik team if you are interested in working with us in this area. Piwik is an open platform, our long term vision is that Piwik 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 Piwik?

To uninstall Piwik, follow the following steps:

  • Remove the Piwik Tracking code from all websites previously tracked with Piwik
  • Delete all 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 Piwik tables

Piwik will then be successfully uninstalled.

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

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

  • Upload the latest Piwik release to your server
  • Before you install Piwik, modify the config/global.ini.php file, and under [database] section change from type = InnoDB to type = TokuDB
  • Install Piwik by going through the few steps. Piwik 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 Piwik Analytics service!

How do I backup Piwik data and files?

To backup Piwik:

  1. Regularly backup the Mysql database containing 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 Piwik backup:

  1. Import the Mysql backup data in a new Mysql database you have created
  2. Download the latest version of 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 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 Piwik Mobile graphs?

Static image graphs in the PDF/HTML reports and Piwik Mobile app will display standard non unicode characters by default. However if you use 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 Piwik You can find here:

We are social

Follow us: