How do I install Piwik?

First, download Piwik here. Then, please see the 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 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 Hosting page.

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 Piwik on Softaculous or Piwik on Installatron for more details.

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 configure Piwik when the server is installed behind a 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:

[General]
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:

[General]
; CloudFlare proxy
; proxy_client_headers[] = HTTP_CF_CONNECTING_IP
; ISP proxy (Client-IP)
;proxy_client_headers[] = HTTP_CLIENT_IP
; standard proxy
;proxy_client_headers[] = HTTP_X_FORWARDED_FOR
;proxy_host_headers[] = HTTP_X_FORWARDED_HOST

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

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

In the Piwik installation at the Database setup step, the host can be specified as:

  • hostname
  • IPaddress

You can specify a custom port number to connect Mysql (instead of default 3306):
* host name:port
* ipaddr: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

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.
  • 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 piwik.example.org and is now installed 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 might have to update or setup the script path in your cron 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?

If you want to keep the data in your Piwik, but move the php files to another server and the data to another mysql server, you will need to:

  • Export your mysql database in a file; you can use tools such as phpmyadmin to do this. Note that 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 very 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. It is very important that you 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 builds.piwik.org 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 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 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.

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

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