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
Please see the Piwik Requirements for further information.
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].
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.
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.
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 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.
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 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.
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:
Connect to your MySQL database:
$ sudo mysql
Create a database for Piwik:
$ 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 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 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.
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:
[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] ; 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
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:
[General] ; 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)?.
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.
During the 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 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 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
[General]section, add a line with your new host:
trusted_hosts = "example-stats.net"
- open the new Piwik URL in your browser, and check that Piwik 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 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
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 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 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 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 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 Piwik via the web interface: https://piwik.org/docs/installation/ # 5) Disable Piwik development mode ./console development:disable
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 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 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
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.
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.
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.phpfile, and under
[database]section change from
type = InnoDBto
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.phpfile and below
[database]add a new line:
type = TokuDB.
- Enjoy your high performance Piwik Analytics service!
To backup Piwik:
- Regularly backup the Mysql database containing 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 Piwik backup:
- Import the Mysql backup data in a new Mysql database you have created
- Download the latest version of 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 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:
- 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