How do I make Piwik faster?

By default, Piwik reports are processed when you request them in the User Interface. Please see How to setup auto archiving of your reports every night? to automate the generation of Piwik reports. See also How long does the Piwik archiving process? for expected speed for high traffic websites.

If you are running Piwik analytics for a high traffic websites (or hundreds of them), see our guide Optimize Piwik server for speed.

How do I migrate a particular website in Piwik to a different Piwik installation?

You can use the SiteMigration plugin to move a website (and its data) to a new Piwik instance.

How do I import Google Analytics data in Piwik?

It is not yet possible to migrate your Google Analytics data in Piwik easily. We would love to build such tool, please learn more in this blog post and the Github issue.

How do I White Label Piwik, to change the Logo, the Colors, add custom widgets, etc.

We offer an integrated solution for users who wish to customize Piwik, called the White Label plugin.

Using the White Label plugin, we have helped many companies re-brand Piwik for their internal use. We’ve also helped large agencies to deploy Piwik for their hundreds of clients, ensuring a clean branding and interface for all of their users and customers.

Visit Piwik PRO – White Label Plugin to learn more about our White Label offer can benefit you, by seamlessly providing a professional full featured analytics solution. You can buy and download the plugin directly on Piwik PRO website.

How do I exclude traffic from an IP or a range of IP addresses?

To exclude all traffic from a given IP or IP range, log in Piwik as the Super User. Click on Administration > Websites. Below the list of websites, you will find the option to specify “Global list of Excluded IPs”. You can define a given IP address, or IP ranges (132.4.3.* or 143.2.*.* for example) to be excluded from being tracked on all websites. Each Piwik admin user can also specify the list of IPs or IP ranges to exclude for specific websites.

How do I exclude URL query parameters from the URLs tracked, and from Pages reports?

It is common that websites use URLs query parameters or session ID parameters that are not relevant to data analysis (unique ID, meaningless parameter). You can easily ignore a number of parameters from the URLs, and prevent them from appearing in the “Actions > Pages” report. Login as the Super User, go to Administration > Manage Websites > Global list of Query URL parameters to exclude field. Each Piwik admin user can also exclude query parameters for specific websites, by entering them in the Excluded Parameters list for this website, in Administration > Websites.

For example take this URL path: hello.html?module=peace&vid=476tgkg. If you configure Piwik to exclude the URL parameter vid from Page Urls then the URL will be tracked as: hello.html?module=peace.

How do I set the time zone for my reports?

Piwik internally stores all times in UTC, which is a Software Engineering best practise. However Piwik lets you specify the time zone to use for each website in the Websites admin panel. Click on Administration > Websites > Edit. Note: changing the website’s timezone will only affect Reports going forward.

How do I specify the currency used in the Goals revenue reports?

By default, Piwik reports revenues in $ US dollars.

To change the default currency used by Piwik, login as Super User, then click on ‘Administration’, then ‘Websites’. Below the list of websites, you will find a section ‘Default Currency for new websites’. There you can specify the currency to use by default in Piwik for new websites.

To change the currency of a given website, go to ‘Administration’ then click on ‘Websites’ then click ‘Edit’ next to a website. In the column ‘Currency’ you can choose a new currency for this website.

How do I specify which websites to load by default in Piwik?

Login to Piwik, in the top menu click on your username, then in “Settings” you may select the website to load by default under “Report to load by default”.

Each user can specify which websites should be loaded in Piwik. Alternatively, users can choose to load the All websites dashboard, which gives an overview of the status and evolution of all websites available to the user.

How do I specify the date used by default in Piwik reports?

By default, Piwik will load reports for “yesterday”. Each Piwik user can specify, in their “User settings” admin panel, the date to load by default in Piwik reports: “Today”, “Current week”, “Current month”, or “Last 7 days”, “Last 30 days”, “Yesterday”, etc.

How do I control the categories tree structure in the Page URLs and Page titles reports?

By default, Piwik will report your Page URLs and Page titles in ‘categories’, automatically constructed based on the slash character / as a delimiter.
For example, a Page with a URL “” will be reported under the category “about” in the Page URLs report. When you click on it it will open the pages inside this category, and show the stats for the subpage “contact”. This feature is very useful because it helps visualize which sections of your website have the most traffic, rather than having all your page URLs at the same level.

This grouping feature is also very useful with Page Titles. You can use it for tracking custom flash events (“game / clickStart”, “game / registerNewUser”), video events (“videos/ bestOf2011 / start”, “videos/ bestOf2011 / pause”), simply organize your pages into a easier to analyse structure, etc.

In the Piwik Javascript tracking code, you can specify custom page titles by calling piwikTracker.setDocumentTitle() (Learn more about the JS Tracking API). For example, to track a custom page view when a user clicked on a button in your web app, you could write

piwikTracker.setDocumentTitle("ajax/click view button");

You can also customize the delimiter to use for splitting your page URLs and Page titles into categories (or disable the feature by setting the delimiter to a character not in use in your Page titles). Edit your config/config.ini.php file, and set the following:

action_title_category_delimiter = ::

You can then define your custom page names as follows:

piwikTracker.setDocumentTitle("Products :: Gardening :: Seeds id=123");

and your pages and categories will be grouped according to the :: delimiter.

How do I add more than the default 5 custom variables?

By default Piwik provides five custom variables. You may configure Piwik to track more custom variables. New custom variable slots will be created in both the ‘visit’ scope and ‘page’ scope.

First you need to be able to connect to the server running Piwik over SSH, so you can type commands to the Piwik console. To increase the custom variables slots from 5 to 10, type in the terminal:

$ cd /path/to/piwik
$ ./console customvariables:info

  Your Piwik is configured for 5 custom variables. 

$ ./console customvariables:set-max-custom-variables 10

You can now track up to 10 custom variables in the visit and page scope. Enjoy!

After the top 500 or top 1000 rows, Piwik automatically groups pages, keywords, websites, etc. under the label “Others”; How do I force Piwik to not limit the data?

For performance reasons, Piwik will by default only archive the first top 500 pages, top 1000 keywords, top 1000 websites, Custom Variables, etc. Piwik will then sum all the remaining pages, keywords, etc. under the label “Others”. If you wish to archive all the data, or simply archive more than the current rows limit, you can override these values in the configuration file config/config.ini.php. For example, to limit all table to 5000 entries, add the following in config/config.ini.php:

; maximum number of rows for any of the Referers tables (keywords, search engines, campaigns, etc.), and Custom variables names
datatable_archiving_maximum_rows_referers = 5000
; maximum number of rows for any of the Referers subtable (search engines by keyword, keyword by campaign, etc.), and Custom variables values
datatable_archiving_maximum_rows_subtable_referers = 5000
; maximum number of rows for any of the Actions tables (pages, downloads, outlinks)
datatable_archiving_maximum_rows_actions = 5000
; maximum number of rows for pages in categories (sub pages, when clicking on the + for a page category)
datatable_archiving_maximum_rows_subtable_actions = 5000
; maximum number of rows for any of the Events tables (Categories, Actions, Names)
datatable_archiving_maximum_rows_events = 500
; maximum number of rows for sub-tables of the Events tables (eg. for the subtables Categories>Actions or Categories>Names).
datatable_archiving_maximum_rows_subtable_events = 100
; maximum number of rows for the Custom Variables names report
datatable_archiving_maximum_rows_custom_variables = 5000
; maximum number of rows for the Custom Variables values reports
datatable_archiving_maximum_rows_subtable_custom_variables = 5000

After doing this change, if you want your old reports to be re-processed with this new number of rows, see FAQ on how to re-process reports.

How do I track impressions and clicks and CTR of image banners and/or internal banner ads or text ads?

Piwik provides a powerful and easy to use functionality that is designed to help you measure how many times a piece of Content was seen by your users, and how many times it was clicked on. We call this feature Content Tracking. Content Tracking reports how often a specific ad or a banner was displayed on any of your pages and how often a visitor actually interacted with them. We call these two parts content impression and content interaction. This feature is not only limited to ads or banners. You can use it for any kind of content. Learn more about Content Tracking.

How do I force the reports to be re-processed from the logs?

In some rare occasions it may be useful to force Piwik to re-process the reports from the original logs. By default, reports will only be processed once (preferably with an automatic cronjob setup to run every hour) and then archived in the database. When you visit the Piwik UI for a previous day (or week, month, etc), all you see is pre-processed data read directly from these archive tables.

Warning: to reprocess reports for specific dates, you need access to the historical visitor Log Data. Make sure you are not using the feature ‘Delete old logs‘ on your Piwik server. If you have deleted some of your old logs, Do Not Proceed! Some of your data could be lost forever.

1) Cleanup the existing archived data

To force Piwik to re-process your reports you can use one of the following solutions:

  • (Recommended) To reprocess reports for a specific day, or specific period, you can delete the two Mysql tables piwik_archive_* for the specific month containing the dates to re-process. To delete the tables, you can use a tool such as phpMyAdmin which is usually provided by your web host.
  • or if you wish to reprocess archiving for all reports for all dates, you will have to delete all piwik_archive_* tables in the Piwik Mysql Database. To delete report data for one full year including monthly reports, you may have to delete up to 24 tables (12 months * 2 tables).
  • or you can also call the API to tell Piwik that old data was imported
  • or you can edit your config/config.ini.php file, and set (when you are done, do not forget to set these values back to 0):

    always_archive_data_day=1 ; force archiving of all daily reports
    always_archive_data_period=1 ; force archiving for all period reports (week, month, year)

You are almost done!

2) Re-process your reports

When you login your Piwik, Piwik will re-trigger the processing of the report data which will re-create the archive tables. This may take one second on a small website but it could take several minutes for bigger websites.

When you want to ensure that reports load fast, run the following command to pre-process your report data for all websites:

./console core:archive --force-all-websites --force-all-periods=315576000 --force-date-last-n=1000 --url=YOUR_PIWIK_URL_HERE

(this command is a little customisation of the standard core:archive cron command.)

Conclusion: you have re-processed your data and it should now appear as expected in your dashboard.

How do I force Piwik to use SSL (https) for improved security?

Configuring Piwik so that all requests are made over SSL (https://) is an easy way to improve security and keep your data safer. To ensure that logins, passwords and the token_auth are not sent in the clear, you can manually set a config file setting.

  • First of all, make sure that your Piwik server is configured so that requests to work as expected. We also recommend you use a valid SSL certificate.
  • In your config/config.ini.php file, add the following under the [General] section, set the following:

    force_ssl = 1

Piwik will then automatically redirect all http:// requests to route to the https:// equivalent. Learn more tips about how to secure Piwik.

How to track error pages (404 pages) in Piwik? Which URLs are 404 and which referers lead to these pages?

Pages regularly appear and disappear on websites, other websites might link to wrong URLs on your website, etc. You can track with Piwik which URLs are leading to a 404, and which referer pages link to 404 on your website.

  • Setup a custom 404 page: you can easily do this if you use a CMS (for example, in wordpress, all 404 pages are loading a custom 404 template). If you don’t use a Content Management System, you can usually specify a 404 custom page in your webserver configuration file.
  • Add the Piwik tracking code in this custom 404 page. In the Javascript tracking code, add the following:

    _paq.push(['setDocumentTitle',  '404/URL = ' +  encodeURIComponent( + '/From = ' + encodeURIComponent(document.referrer)]);

before the line

  • In your Piwik report, in Actions > Pages Titles, you will now have a new entry for the 404 pages. It will also list the full URL of the 404 pages, as well as all referers leading to this page. Enjoy!

How do I track visits on my intranet?

Piwik can track visits on your intranet website as long as Piwik itself is hosted in your intranet. To make sure that all unique visitors are tracked correctly in your intranet, there are two choices:

1) Either make use of User ID feature to assign your users with a unique persistent User ID string. This will make sure your users are tracked accurately across all devices. Learn more in User ID guide.

2) Alternatively if you cannot use User ID then please edit your config/config.ini.php and add the following:

trust_visitors_cookies = 1

This will ensure that even if all visitors have the same IP, browser configuration, OS, etc. they will be counted as unique visitors based on the first party cookies. If not set, you will see a lower number of visits.

Note that this setting will also apply to your non intranet websites if you track in your Piwik both intranet and internet websites. We plan to differentiate between Websites and Intranets in a future version (more info).

If you use SharePoint for your intranet, check out our SharePoint Analytics product.

How do I automatically login my users in Piwik when they go from my CMS to Piwik?

Some Piwik users automatically provide their CMS customers with Piwik statistics. If you want to provide a one-click automatic login to Piwik for your users, you can use the ‘logme’ mechanism, and pass their login & the md5 string of their password in the URL parameters:

This will securely login the user (create a cookie in their browser) and redirect to the index.php on successful login. Note that this authentication method doesn’t work for a user with Super User access.
You can also specify the URL to redirect after a successful login, if different from the default Piwik dashboard page:

You can also specify a website ID (idSite) that will be loaded by default after the redirect:

Important: we recommend to make this request over https (SSL) in order to keep the password hash secure.

How do I generate fake data (generate visits, actions, conversions, etc.) in Piwik?

When you are testing Piwik it may be useful to generate test data. Learn how to generate test data in Piwik in this post using the VisitorGenerator plugin.

How do I enable users to login into Piwik inside an iframe?

By default, the Piwik login screen will not load in iframe, as a security measure to prevent clickjacking. You can manually enable Piwik login screen to work from inside an iframe by adding the following config file setting in your config/config.ini.php:

enable_framed_pages = 1

Instead of loading the login screen in an iframe, you might want to use the logme() method to automatically log your users in Piwik remotely. To include any Piwik report or widget via an iframe, click to see this FAQ.

How do I include Piwik reports within an Iframe?

For security reasons, including Piwik in an iframe first require you make small change to your config/config.ini.php file: see this FAQ.

How do I specify the URL that users should be redirected to, when they logout of Piwik?

By default when user logs out he is redirected to the Login form. In your config/config.ini.php you can add under the [General] category the option:


When the user logs out, he will be redirected to this URL instead.

How do I delete all statistics for a given website, or for all websites?

It is possible to keep all the websites information (names, defined goals, etc.) and only delete the stored analytics data. There is not currently a tool available to delete all data automatically, but you can manually delete all data for a specific website directly within the database server.

Connect to your Mysql database storing your Piwik data with your favorite database client (for example phpMyadmin) and do the following:

  • To delete statistics data for all websites, run the following query for each piwik_archive_* table:

    DROP TABLE piwik_archive_numeric_Y, piwik_archive_blob_Y;
  • To delete statistics data for a given website, run the following query for each piwik_archive_* table:

    DELETE FROM piwik_archive_numeric_Y, piwik_archive_blob_Y WHERE idsite = X;

The archive tables will automatically be re-created from the Visitor logs when Piwik processes your reports (assuming you do not purge your old visitor log data).

  • To delete log data for a given website, execute the following query:

    DELETE FROM piwik_log_visit WHERE idsite = X;
    DELETE FROM piwik_log_link_visit_action WHERE idsite = X; 
    DELETE FROM piwik_log_conversion WHERE idsite = X; 
    DELETE FROM piwik_log_conversion_item WHERE idsite = X;

with X replaced by the website ID you wish to reset.

The alternative solution is to use the Delete old reports and Delete old tracking data features, click to see the FAQ.

If you want to delete Visitor log data (and not Report data) then read this FAQ: How do I delete old visitors statistics for a given website and/or date?

How do I set some of my website directories or pages to not be tracked?

If you wish to set some specific pages or directories to not be tracked by Piwik, we recommend that you modify the Piwik Javascript Tracking code, and replace


by a small if statement to test whether the current page must be tracked or not.
To exclude traffic for all page URLs which contain /admin or which contain user/private, write:

if (!window.location.pathname.match(/(\/admin|user\/private)/))

In this example, all URLs except the ones containing “/admin” or “user/private” will be tracked by Piwik.

How do I configure my Piwik server to allow cross domain requests? (CORS)

Piwik is an analytics platform that collects data (Tracking API) and reports (Analytics API) this data in interesting formats. Sometimes you want to query this data from across other domains for example using cross-domain Ajax calls (XMLHttpRequest).

By default browsers implement the same-origin policy which prevents browsers from directly requesting data from other domains. Luckily, modern web browsers allow developers to perform cross-domain requests with one trick: the server must allow cross-domain requests by responding to the request with the Access-Control-Allow-Origin header set to a value that includes the domain of the requesting code (or * to match all domains).

To enable your Piwik server to serve data, edit your config/config.ini.php file. To allow your Piwik to serve data to all domains:

cors_domains[] = *

To allow Piwik to serve cross-domain requests to only and

cors_domains[] = ""
cors_domains[] = ""

Reference: Cross-origin resource sharing.

How do I delete old visitors statistics for a given website and/or date?

Sometimes, you may need to delete all Visitor log data for a given date, and/or a given website. For example if you have imported log files incorrectly in Piwik you may want to delete the invalid data that was imported. In Piwik 2.14.0 we released a new console command which you can use to delete all visitor log data (including Visits, Actions, Goal conversions, Ecommerce activity).

To use this console command, login to your server (using SSH) and go in the Piwik directory. Execute the following command to display the help:

./console help core:delete-logs-data

The following options are available:

  • --dates lets you delete log data with a date within this date range. Eg, 2012-01-01,2013-01-01
  • --idsite lets you delete log data belonging to the site with this ID. Comma separated list of website id. Eg, 1, 2, 3, etc. By default log data from all sites is purged.
  • --limit lets you pick the number of rows to delete at a time. The larger the number, the more time is spent deleting logs, and the less progress will be printed to the screen. (default: 1000)

For example to delete all log data for month of January 2015 on website ID 42, execute:

./console core:delete-logs-data --dates=2015-01-01,2015-01-31 --idsite=42


  • all the visitor log data for the given date range and website ID will be permanently deleted.
  • this console command does not delete your archived report data but only delete the raw visitor log data.

Related FAQs

If you want to configure Piwik to automatically purge your old data (whether visitor log data, or statistics reports data), see this FAQ How do I delete historical Piwik data? (purge old logs and/or old processed reports)

If you want to delete old reports, read this FAQ: How do I delete all statistics for a given website, or for all websites?

How do I get reports for a custom date range?

Piwik reports on days, weeks, months and years, and you can also specify a Custom Date Range in the Calendar. Click on the calendar, then on “Date Range”. Now select on the left calendar the starting date for the range, and in the right calendar the end date of the range. Piwik will process in real time the reports for the requested date range.

In the Analytics API, you can also get reports for a custom date range. For example, to request any report for the range “Feb 15th – Feb 25th”, you would use the parameters:


How do I search within reports?

Most data table reports have a small search bar below the report. Here you can type data and press Enter key to search for this string within the report displayed above. For example, in the “Keywords” report, you can search for nature and it would return all keywords matching nature.

The search field is actually a Regular Expressions. For example, a search for nature|life would match all rows containing nature or life. All search strings containing any of the special characters from this list: . + * ? [ ] $ ( ) { } = ! | must be escaped with a back slash, eg. if you want to search for keywords containing love! you would search for love\!.

(Advanced note: to find all rows in the report that do not include a particular sub-string eg. brand, you would use the regular expression: ^((?!brand).)*$)

How do I change the default email address “From:” in PDF reports emails?

You can edit the default email address that will appear in the PDF reports emails by editing the configuration file config/config.ini.php, and adding under the


section, the following line:

noreply_email_address = ""

All reports by email will now be sent from “”

How do I change the default email address “From:” in password reset emails?

You can edit the default email address that will appear in the password reset emails by editing the configuration file config/config.ini.php, and adding under the


section, the following line:

login_password_recovery_email_address = ""

All password reset emails will now be sent from “”

You may also change the email sender name by setting:

login_password_recovery_email_name = Piwik

and you may also change the Reply-to email address and name:

login_password_recovery_replyto_email_address = "no-reply@{DOMAIN}"
login_password_recovery_replyto_email_name = "No-reply"

How do I send Piwik emails using Gmail SMTP server?

You can configure Piwik to use GMAIL as the mailserver. To do so, login as Super User, go to Administration > General Settings, and configure the form as follows:

  • Use SMTP server for e-mail: YES
  • SMTP server address:
  • Authentication method for SMTP: Login
  • SMTP username: your gmail username
  • SMTP password: your gmail password
  • SMTP encryption: SSL

All Piwik emails (Scheduled PDF Reports, Password reset confirmation, etc.) will now be sent using Gmail servers.

On a Windows server using IIS, the pages “Default.aspx” and “default.aspx” are tracked as different pages, but they are the same. How do I force Piwik to record them as the same page?

In your Piwik Javascript Tracking tag, add the following line:

_paq.push(['setCustomUrl', location.href.toLowerCase()]);

just before the line:


All your pages will now be tracked as lowercase, eg. “Default.aspx” or “DEFAULT.aspx” will be tracked as “default.aspx”.

If instead of the Javascript Tracker you are using the Log Analytics tool, then you can pass the following option to the script:


How do I track a Phonegap app with Piwik?

To measure your Phonegap app with Piwik, you can include the default JavaScript Tracking code in your app pages. Then you will need to make one change to the default Tracking code:

  • Locate the line: var u="//{$PIWIK_URL}";,
  • Replace it with the following: var u="http://{$PIWIK_URL}";. Note that http: or https: is pre-pended in front of your Piwik URL.

Congratulations: your Phonegap app users will be correctly tracked in Piwik.

How do I track the URL Hash tags so that the #hash appears in the Page URLs report, and in Visitor Log?

By default Piwik will remove the #hashtag part of the URL, to keep reports clean for most users. However it is common that you wish to record the hash tags as they may contain interesting and relevant information.

To track URL hash tags (enable/disable) login as Super User, click on “Administration” and on “Websites”.

  • In the “Global websites settings” section, below the “Page URL fragments tracking” title, you can enable Hash tags tracking by enabling the checkbox “Keep Page URL fragments when tracking Page URLs”. This setting will be applied to all websites.
  • You may also enable/disable Hashtags tracking for each individual website. In the listing of Websites, click “Edit”. In the column “URLs”, below the help notice, you will find a checkbox “Keep Page URL fragments when tracking Page URLs”, which lets you set your preference for websites.

Note: even if #hashtags tracking is disabled, tracking Campaign parameters via the hash tag will still work as expected.

How do I track my RSS/Atom feed subscribers?

Until Oct 2012, Piwik was relying on Feedburner and the ‘Awareness API’ to provide RSS. It used to provide the following information:

  • Reach: Reach is the total number of people who have taken action — viewed or clicked — on the content in your feed.
  • Circulation: Circulation is an approximate measure of the number of users who requested your feed. This is the “Readership count”.
  • Hits: Hits are a raw measure of request traffic for your feed. This metric includes automated bots requests, visitors viewing the feed but not subscribing, etc.

Unfortunately, Feedburner now owned by Google decided to shut down permanently their API. We are now considering doing Feed Analytics using Piwik. We are looking for supporters & funding to build a simple script that will track RSS & atom feeds usage! If you would like to help fund this feature, please get in touch with the core team or post a comment on this ticket.

How do I momentarily disable Piwik User Interface and/or Piwik visitor Tracking?

Before a Database upgrade on a high traffic Piwik server, it is highly recommended to:

  • disable Piwik Tracking: in the config/config.ini.php, add the following
record_statistics = 0

This will cause all Piwik Tracking requests to return quickly the 1*1 gif beacon, without connecting to the Database or doing any processing.

  • disable the Piwik User Interface: you can also disable the User Interface, which will display a maintenance message instead of the standard Piwik UI. If you run the Piwik Database Upgrade script using the shell/console command, we highly recommend to turn Piwik off while the upgrade is in process. Disabling the Piwik User Interface will prevent other users from accessing Piwik while the Database upgrade is in process.
    To do so, add the following in the config file:
maintenance_mode = 1

When maintenance_mode is on, the API is also disabled. For example, the XML message returned is:

<result><error message="Piwik is in scheduled maintenance. Please come back later. "/></result>

When the Piwik update is finished, do not forget to re-enable Visit Tracking and/or the User Interface.

How do I enable “Unique Visitors” metric for Yearly reports and for Custom Date Ranges?

By default Piwik will not process the number of Unique Visitors for Years and Custom Date Ranges (for performance reasons). The query to process the number of unique visitors is quite costly and takes seconds or even minutes to run on a High traffic Piwik server. You can decide to enable or disable the unique visitors metric for specific periods by adding the following in your config/config.ini.php

enable_processing_unique_visitors_day = 1
enable_processing_unique_visitors_week = 1
enable_processing_unique_visitors_month = 1
enable_processing_unique_visitors_year = 0
enable_processing_unique_visitors_range = 0

By default, unique visitors are processed for days, weeks and months (they are set to 1). You can for example enable yearly unique visitors by setting enable_processing_unique_visitors_year = 1

Note: processing the Unique Visitors metrics is using the Piwik logs. This requires that the feature “Delete old logs” is not used on your Piwik server.

How do I setup Piwik to track multiple websites without revealing the Piwik server URL footprint which appears in the Javascript code in all websites?

By default, the Piwik Javascript code on all tracked websites contains the Piwik server URL. This is fine for most users, but someone (eg. a competitor) could run a script that would look at thousands or millions of websites and search for your Piwik server URL in the source code of these websites. This person could then find out all websites tracked in your Piwik instance. In some cases you might want to hide this Piwik URL completely while still tracking all websites in your Piwik instance. It is possible to do by modifying your Piwik Javascript code, and point it to a “proxy piwik.php script” instead of your Piwik server URL. This piwik.php script has to be uploaded on each of the websites tracked, and will automatically “forward” all requests to your secret Piwik server.

  • All documentation on how to install this script is at piwik/tracker-proxy.
  • Follow the instructions carefully and you will then have all your websites tracked without revealing your common Piwik URL, ensuring that nobody can find out the websites tracked by Piwik!

Note: when you use this technique, the feature to exclude visits via the ignore cookie will not work. You may also be interested in White label plugin for Piwik to provide a customised Piwik colors and product name to your clients.

How do I get the number of active unique users to my app?

Piwik measures your users and their interactions with your website or app. In order to accurately measure the number of known and active unique users to your app, you can use the User ID feature which will let you assign User ID string to each of your signed-in users. When this User ID is assigned then Piwik will calculate a new metric called “Unique users”. This metric is reported in Visitors > Overview report and will also appear in the VisitsSummary.get API response under nb_users metric (more info). This metric represents the number of unique active users (visitors with a known User ID). Learn more in the User ID guide.

How do I enable third party tracking cookies, as well as the existing first party cookies?

In some cases, it might be interesting to enable third party cookies, so that a same visitor will get the same ID across all your domains and subdomains. Piwik doesn’t report cross sites visits at this stage, so you will benefit from using third party cookies only if you run manual queries against Piwik database. To enable 3rd party cookies, edit your config/config.ini.php and add the following lines:

use_third_party_id_cookie = 1

When this is enabled, Piwik tracker will serve a third party cookie containing an id visitor (16 chars ID). This ID will be the same for this visitor across all websites, and is stored in the database field “idvisitor”.

How do I customize the Piwik Campaign parameters pk_campaign and pk_kwd?

By default, tracking campaigns in Piwik involves adding the required parameter pk_campaign (and optional parameter pk_kwd) to the URLs pointing to your website. Piwik also supports Google Analytics campaign parameters (utm_*).

Here is a comma delimited list of default parameter names that Piwik will read:

 campaign name parameters: pk_campaign, piwik_campaign, utm_campaign, utm_source, utm_medium
 campaign keyword parameters: pk_kwd, piwik_kwd, pk_keyword, utm_term

It is also possible to customize these parameter names. For example, we would like to use the parameters names “campaign” (instead of pk_campaign) and “keyword” (instead of pk_kwd). To do so, there are two required steps:

  • 1) Override the parameters in the config file. In your config/config.ini.php, add the following:


Note: you may specify a comma separated list of campaign parameter names, in case you wanted Piwik to read the campaign name or value from several possible parameters. The first non empty value will be used.

  • 2) Customize the parameters in the Javascript. In the Javascript snippet on all your pages, add the following before the trackPageView() call:

    _paq.push(['setCampaignNameKey', 'campaign']);
    _paq.push(['setCampaignKeywordKey', 'keyword']);

Note: these two functions also accept an array of strings. If an array of names is specified, the first non empty campaign or keyword parameter value will be selected.

Note: the Campaign parameters can be used in the query string or in the hash as well (for cleaner canonical URLs), such as: “landing.html#pk_campaign=my campaign”

How do I configure outgoing (forward) proxy in Piwik (eg. squid)?

It is possible to configure a forward outgoing proxy in Piwik, so that all outbound Internet connections (eg. to check for new versions of Piwik, for SEO plugin, Plugin updates, etc.) go through the proxy. Check the FAQ Configure Outgoing proxy for more details.

How do I exclude / ignore my traffic from Piwik?

There are a few ways to tell Piwik to exclude and ignore your traffic:

  • Set the ‘ignore cookie’: Login in Piwik, click in the Username in top menu, then in the ‘Settings’ page click the link below the section ‘Exclude your visits using a cookie’.
  • You may ignore all traffic from a given IP or IP range (useful if you use a static IP): check this faq.
  • You may also exclude particular User Agents from being tracked in Piwik.

Note: when you exclude some traffic, it will only exclude it going forward and is not applied retroactively.

I forgot my password or username, how do I reset my password?

To reset your password in Piwik, go to Piwik: below the login screen you will find a link “Lost your password?”. After clicking the link, enter your Piwik username or Email address, and enter your new password (twice). A link to confirm your password reset will be sent to your email address.

Note: for security reasons, it is not possible to recover passwords, but only change them. We highly recommend to use a strong password and to enable automatic SSL for login screen in your Piwik server.

How do I change the Super User’s password when password recovery emails are not sent?

If you use Piwik 2.1 or newer:

  1. Connect to your Piwik database using a tool such as phpMyAdmin or direct Mysql access.
  2. The following SQL query must be executed on your database. Replace the ‘admin’ with your Super User username. Note that it must be replaced twice in this SQL query.

    UPDATE `piwik_user` SET `password` = MD5( 'changeMe' ), `token_auth` = MD5( CONCAT('admin', password)) WHERE `login` = 'admin' AND superuser_access = 1 
  3. Login to Piwik using the following credentials:

    login: admin 
    password: changeMe
  4. Click on the username link in the top menu, then change your password to a more secure one.

  5. Check you are using the most up to date version of Piwik.

If you use Piwik older 2.0.3 or older:

  1. In your config.ini.php, change the [superuser] section to:

    login = "admin"
    password = "807ff71b3301262e222ad05e5b7c4325"
    email = ""
    salt = "ffd09b1b27ad925d2a3ca842947f391d"
  2. Login to Piwik using the following credentials:

    login: admin 
    password: ChangeMe
  3. Go to Administration -> User settings, then update your email and change the password, click Save.

  4. Update Piwik to the latest version as soon as possible!

How do I find the visitor IP Addresses?

Piwik by default tracks the full IP address of all visitors to your site (you can anonymize this IP if you wish).

To view your visitor IP addresses:

  • In the User Interface, click Visitors > Visitor Log. The Visitor Log will display a list of all the visits during the selected calendar period, and for each visitor will display the IP address in the left.
  • you can also fetch the visit IP addresses of a given visitor, or all visitors in a selected date range, using the Piwik Analytics Live! API.
  • you may also see the Visitor IP on the Visitor Profile report
  • the raw data is also available in the database, in tables piwik_log_* See this FAQ.

Note: in both cases, the IP address will only be displayed if you are logged in Piwik: for privacy reasons, IPs are never displayed to the anonymous user.

How do I exclude from statistics all requests with a specific User Agent?

Sometimes, there are non human (bots) that visit your website. These bots can have many purposes (such as security scanning, performance scanning, monitoring, search engine bot, spam bot, etc.). Often, you do not want these bots to be tracked in Piwik, because you may want to focus on how humans use the website, and not bots. In this case, you can tell Piwik to exclude traffic where the User-Agent of these requests match a given string.

To exclude traffic for a particular User agent (or several user agents), go to “Administration”, click on “Websites”. Below the list of websites, you will find the option to specify “Global list of user agents to exclude”. You can enter there a list of user agents to exclude from being tracked by Piwik. If the visitor’s user agent string contains any of the strings you specify, the visitor will be excluded from Piwik. You may also toggle the checkbox “Enable website specific user agent exclusion.” to enable this feature as a new column for each website in the Websites listing.

Note: when you exclude some traffic, it will only exclude it going forward and is not applied retroactively.

See also: Exclude traffic from IP address or IP ranges

How do I select IP addresses or Visitor ID directly from the database?

In the database, the IP addresses and Visitor IDs are stored in Binary form for storage efficiency. To display these values correctly you can use the following SQL query:

SELECT inet_ntoa(conv(hex(location_ip), 16, 10)) as ip, conv(hex(idvisitor), 16, 10) as visitorId FROM piwik_log_visit;

How do I make Piwik report data public and viewable by anyone?

By default, report data and all information in your Piwik server are protected and nobody can access it. To view and access any analytics data, Piwik always asks you to sign in with a valid user account.

Some Piwik users may want to make their analytics data open and viewable by anyone. For example if you run a NGO, an open governmental service, an open source project, etc. the analytics data may be of use and interest to many people in your community. By making your Piwik data and communicating that your analytics data is public, members of your community may help you analyse the data and find interesting insights to drive you to overall do better work.

Before you decide to make your analytics data public, please consult with your colleagues and team members and make sure that everyone agrees with this decision.

If you wish to make all analytics data publicly viewable for a particular website, follow these steps:

  • Login to Piwik as an Administrator or a Super User
  • Go to Administration > Users
  • Under “Manage access”, locate the “anonymous” user
  • Click on the “View” icon to set the anonymous the right to view data for this website

If you later want to remove public access access to your data, follow these steps:

  • Under “Manage access”, locate the “anonymous” user
  • Click on the “No Access” icon

Note that when an anonymous user (not signed in) visits your Piwik dashboard, we do our best to protect privacy and hide from display any Personally Identifiable Information (PII):

  • Visitor Profile feature is disabled for the anonymous user
  • the Visitor IP address and the Visitor ID are not displayed in the UI or API responses for the anonymous user

How do I record tracking data in the past, and tell Piwik to invalidate and re-process the past reports?

This question is aimed for users who use the REST Tracking API to manually insert visits and actions in Piwik. The parameter cdt lets you define the date and time of the page view. If you set this date to a date in the past (for example, 3 days ago) and that Piwik has already processed the statistics reports for this date, you will not see the newly added data in Piwik.
To tell Piwik that past data was recorded after-the-fact and force the archiving to happen again for this date, you can use the API function: CoreAdminHome.invalidateArchivedReports. For example if you imported data in the past for a few specific websites on a couple different dates you could write:


The next time auto archiving will run will automatically re-process the data for these particular dates.

Note: in rare cases you may want to delete reports for a particular period (one of: day, week, month, year, range). You may set the &period= parameter to the API call, this will force Piwik to only invalidate reports of the specified period.

How do I improve Unique Visitor detection accuracy?

If you import your server logs in Piwik, you may have noticed that in this case Piwik does not track Unique Visitors as well as when using the Javascript tracker. You can configure Piwik to improve the detection of “Returning Visitors” and unique visitors.

For example, to configure Piwik to lookup a visitor up to 30 days (30*86400 seconds) in the past, you would set:

window_look_back_for_visitor = 2592000

Note that by default, Piwik looks only in the past 30 minutes. We do this for performance reasons: to keep Piwik tracking fast, even if you track hundreds of thousands or millions of unique visitors per month.

If you do not use Log Import but use JavaScript tracker or another client, you can still improve the tracking of unique visitors and unique devices. See this FAQ for more information: How do I get the number of active unique users to my app?

How do I create new visit on demand, so that several users using the same computer or browser are counted separately?

Piwik tries to guess visitors and unique visitors using several elaborate techniques (User ID, first party UUID cookie, heuristics matching user settings, etc.). If several people use the same system or browser, Piwik might count them all as one visitor. If you want to track a user’s request across multiple devices (laptop, smartphone, tablet) then you must use the User ID feature.

If you cannot use User ID to track unique users, it is still possible to force Piwik to create a new visit for the current request whenever you require it. To create a new visit on demand you can use the &new_visit=1 parameter in the Tracking API (see Reference docs).

If you are using the Javascript tracker, you are also able to create new visits on demand. In your website in Javascript, whenever a user logs in the system (or whenever there is a need to create a new visit) you may write the following (before the trackPageView call):

_paq.push(['appendToTrackingUrl', 'new_visit=1']); // (1) forces a new visit 
_paq.push(["deleteCookies"]); // (2) deletes existing tracking cookies to start the new visit
// the two lines must be above the call to track* function

When the page loads, a new visit will be created in Piwik.


  • this code should only be displayed once after the user has logged in; if you leave this code in all the page views, it would create a new visit for each page view and make your Piwik reports much less useful.
  • it is recommended to use User ID instead when possible.

How do I create new visit whenever a user visits my website using a new campaign or a new website referrer?

Piwik tracks users on your websites or apps, and will group actions of a same user into a visit. Here are some rules which are applied to assign actions to visit:

  • By default, Piwik will track in a visit all actions done by a visitor within 30 minutes of the last visitor’s action. See this FAQ to learn how to configure this 30 minutes delay.

  • By default Piwik will create a new visit whenever a visitor views your website using a different campaign information from the visitor’s ongoing visit. You can disable this behavior by setting create_new_visit_when_campaign_changes=0 under [Tracker] section in your config/config.ini.php file.

  • By default, Piwik won’t create a new visit when a visitor views your website using a different website referrer information. You may configure Piwik to force it to create a new visit whenever a visitor uses a new website referrer. To do so, edit config/config.ini.php file and under [Tracker] section add: create_new_visit_when_website_referrer_changes=1.

  • You may also create visits on demand by using the Tracking API or Javascript Tracker. Learn more in this FAQ.

How do I get the GeoIP databases to improve accuracy of Country detection, and detect visitors’ Cities and Regions?

The GeoIP databases are sold by MaxMind. MaxMind sells different databases, each with different amounts and types of information.

The country, region and city databases can be used to determine the location of an IP address with different amounts granularity:

  • The country database can only tell you the country of an IP address.
  • The region database can tell you the region and the country.
  • And, the city database can tell you the country, region, city, postal code, geographic coordinates (latitude/longitude) and area code of an IP address.

The ISP and Organization databases can be used to determine the ISP and company of an IP address.

You can find more information on the commercial databases here.

MaxMind also provides two free databases that are less accurate than the commercial ones. One of the free databases can only be used to determine an IP address’ country. The other, called GeoLite City, can be used to determine the same information as the commercial city database.

Needless to say, we recommend using one of the city databases.

Piwik includes a tool that will download the GeoLiteCity database for you. You can access the tool by navigating to Settings > Geolocation.

If you want to install the database by hand, you can download each of the free databases here. Make sure to download the binary versions of the databases.

Keep in mind that geolocation data will eventually become out of date. It is recommended you update your databases at least once a month.* The free databases are updated once a month on the first Tuesday.

Note: The latest version of Piwik includes an auto-updater for the GeoIP databases.

If you are installing the databases manually, then once you get the database you want to use copy it to Piwik’s path/to/piwik/misc/ subdirectory. If you’re using the GeoLite City database, make sure you rename it from




This will help you avoid some potential problems.

How do I install the GeoIP Geo location PECL extension?

If you’re using Ubuntu or Debian run the following command:

sudo apt-get install php5-geoip php5-dev libgeoip-dev

If you have to build the extension by hand, first make sure you have the following installed:

  • PEAR/PECL (which includes the pecl executable)
  • The GeoIP C library with development files
  • Build tools (including GCC, make, etc.)
  • php development files

Then run the following command:

sudo pecl install geoip

Finally, add the following to your php.ini file:

Once the PECL extension is installed, you must configure it. Add the following to your php.ini file:


Replace /path/to/piwik with the path to your Piwik installation.

And finally, if you are using the GeoLite City database there is one more thing you need to do. The PECL extension won’t recognize the database if it’s named GeoLiteCity.dat so make sure it is named GeoIPCity.dat.

Restart the webserver and the GeoIP extension should now be loaded and working in Piwik > Settings > Geolocation.

How do I install the GeoIP module for Apache for accurate Geo location data?

Installing the module

If you’re using Ubuntu or Debian, run the following command:

sudo apt-get install libapache2-mod-geoip

If you’re using a system that uses RPM, you can try the following command:

sudo yum install mod_geoip

If you can’t do either of these, you may have to build the module by hand.

Configuring the module

Open the GeoIP configuration file for the module. It is located at:


Add the following lines to the bottom of the file (replace ‘/path/to/database.dat’ with the path to your GeoIP database):

GeoIPDBFile /path/to/database.dat
GeoIPScanProxyHeaders On

If you have multiple GeoIP databases (for example, a city one and an ISP one), you can add multiple GeoIPDBFile lines.

Restart the webserver and the GeoIP extension should now be loaded and working in Piwik > Settings > Geolocation.

How do I install the GeoIP module for Nginx?

Installing the module

First, check if your build of nginx is already using the GeoIP module. Run the following command:

nginx -V

If the output contains


then you don’t have to do anything to install it. You just have to configure nginx to use it.

If it doesn’t contain


then you’ll have to build nginx yourself, passing




. For more information on building nginx, see this.

Configuring the module

Open your server configuration file and add the following to the http section:

geoip_country  /path/to/CountryGeoIP.dat
geoip_city     /path/to/GeoIPOrLiteCity.dat;



with the path to your GeoIP country database and replace


with the path to your GeoIP city database.

IMPORTANT: For the nginx module, you must provide both a country database and city database. If you just provide a city database, Piwik will not see any country information.

If you’re using an Organization or ISP database, you can add it to the config with:

geoip_org /path/to/GeoIPISPOrOrg.dat

Unfortunately, you can only supply one database here for the nginx module, so if you have both the ISP and Organization database, you will have to pick one to use.

Now make sure the following parameters are passed to fastcgi:

fastcgi_param GEOIP_ADDR $remote_addr;
fastcgi_param GEOIP_COUNTRY_CODE $geoip_country_code;
fastcgi_param GEOIP_COUNTRY_NAME $geoip_country_name;

If you’re using a city database, add the following parameters:

fastcgi_param GEOIP_REGION $geoip_region;
fastcgi_param GEOIP_REGION_NAME $geoip_region_name;
fastcgi_param GEOIP_CITY $geoip_city;
fastcgi_param GEOIP_AREA_CODE $geoip_area_code;
fastcgi_param GEOIP_LATITUDE $geoip_latitude;
fastcgi_param GEOIP_LONGITUDE $geoip_longitude;
fastcgi_param GEOIP_POSTAL_CODE $geoip_postal_code;

If you’re using an organization database, add the following parameters:

fastcgi_param GEOIP_ORGANIZATION $geoip_org;

That’s all, folks. Enjoy!

How do I apply accurate geolocation to old visits, tracked before I enabled geo location?

If you want to know the location of the visits your website received before you started using Piwik with GeoIP, we’ve created a command that will help you. The command will geolocate every one of your visits that have not been located (or just the ones you want to geolocate). Since it goes through many visits in your database, it can take a long time to run.

The command is called usercountry:attribute and can be executed by running (for example):

php ./console usercountry:attribute 2012-01-01,2013-01-01

Things you should note:

  • The command will not work with the Apache GeoIP module, since this requires sending requests through a web server.
  • If you use the GeoIP PHP API it will take longer to run, so we recommend using this command with the GeoIP PECL extension. You can see how to install the PECL extension here.

After you run the script make sure you reprocess your reports so new reports w/ location data will be shown.

How do I get company and ISP information using GeoIP databases?

MaxMind’s Organization and ISP databases can be used to get company/provider information for visitors.

To use them, simply select & purchase the database you want and upload it to the misc Piwik directory.

If you are using a GeoIP server module you may have to do more to get it to work w/ Piwik. The relevant instructions are here for Apache, and here for Nginx.

If you are using the PECL extension and are using a custom directory for your GeoIP databases, upload the new database to this directory instead of Piwik’s misc directory.

Also, make sure Piwik’s Provider plugin is deactivated otherwise the new GeoIP information will be overwritten.

How do I make “Transitions” feature work faster on high traffic websites?

Transitions is a very useful Piwik feature, which is also fundamentally different from most of the other Piwik reports. It does not use archiving to pre-process reports but instead it retrieves its information directly from the logs. This means that the Transitions report can take a few seconds to load on websites with more traffic, but on the other hand, Transitions does not require pre-processing and does not affect Archiving performance.

In our tests, Transitions could handle periods with several 100.000 pageviews quite well. Once you get into the millions, it starts to test your patience. But in general, performance depends heavily on the power of your database server and other things like traffic patterns.

Also, the first time you open Transitions on any page might be a fair bit slower than consecutive calls. This is because after the first time, the database caches are hot and the queries can be executed much faster.

If you have lots of traffic, you shouldn’t open Transitions on long periods of time. But that’s not really a problem because the most important thing is to have enough data in order to get statistically representative results. If you achieve this mass with a single day, it should be fine if you only use it for yesterday (or today).
Since the aggregation happens in the database, you can tune things by adding some indexes to the MySQL tables.

You can create the following INDEX to speed up Transitions on page URLs:

ALTER TABLE  `piwik_log_link_visit_action` ADD INDEX `transitions_url` (  `idaction_url` ,  `idsite` ,  `server_time` );
ALTER TABLE  `piwik_log_link_visit_action` ADD INDEX `transitions_url_ref` (  `idaction_url_ref` ,  `idsite` ,  `server_time` );
ALTER TABLE  `piwik_log_visit` ADD INDEX `transitions` (  `visit_entry_idaction_url` ,  `idsite` ,  `visit_last_action_time` );

We have confirmed that these indexes drastically improve performance for pages that had a fairly low share of the overall traffic. They do add a little extra complexity when inserting new logs but speeding up Transitions also means having the queries it does out of system in a shorter amount of time, which in turn has a positive impact on tracking performance.
You don’t need all of these indexes. Instead, you can add them one by one until the performance of Transitions is satisfactory.

Note: Adding these INDEXes will also increase the Performance of Page Overlay reports.

How do I see the pages that most visitors landed on? How do I access the top pages people use before leaving the websites?

Piwik reports Pages URLs and Page Titles. You can see the Top Entry Pages by clicking on Actions > Entry pages. By default, it shows the top Entry Page URLs, but you can switch to the Entry Page Titles by clicking on the “Related report: Entry Page Titles” link below the report.

Similarly you can access the top pages that people see before leaving the sites, click on Actions > Exit pages. It lists the “worst” Exit Pages URLs by default, but you can access the top exit page Titles by clicking on the Related reports link below the table.

How do I tell Piwik to track Unique Visitors based on the Visitor ID cookie, instead of using IP Address?

By default, Piwik will match a Unique Visitor based on the Visitor ID cookie (if visitor supports cookies) or based on a User fingerprint processed from the IP address and user device information (if visitor does not support cookies).

There are a few use cases when the default Tracker algorithm to track unique visitors does not work as expected. For example if you use Piwik on an Intranet and all users have the same IP address, or if many of your visitors come from a Company or University network and have all the same IP addresses, then Piwik may track many users as one unique visitor.

In these cases you can enable better unique visitors recognition:

  • If your website has a login form, when users sign-in we recommend to tag your users with a User ID.

  • Alternatively if you cannot use User ID then you may force Piwik not use the IP address and device info to decide Unique Visitors but instead rely on the Visitor ID found in the user cookie. To force Piwik to not rely on the IP address as a mean to differentiate one user from another, edit your config/config.ini.php and add a new section [Tracker] with the following:

    trust_visitors_cookies = 1

How do I enable tracking for visitors without Javascript?

By Default, if you use the standard Javascript Tracking Tag, Piwik will only track visitors with Javascript Enabled in their web browser. You can however configure Piwik to also track users with Javascript disabled: to do so, edit the Piwik Tracking Tag <noscript> and change:

<noscript><p><img src="" style="border:0" alt="" /></p></noscript>

Replace with the following:

<noscript><p><img src="" style="border:0" alt="" /></p></noscript>

After making this change and adding &rec=1, visitors with disabled Javascript will execute the noscript and will load the piwik.php image and will have their traffic recorded in Piwik.

Note: the most famous bots will still be ignored with this technique. To force Piwik to track all bots, add the parameter &bots=1 to the tracking URL, eg:

<noscript><p><img src="" style="border:0" alt="" /></p></noscript>

How do I take notes of particular events influencing my traffic?

Often when using Piwik you may have findings from the data, insights, or maybe you just would like to note down the changes you have made on the website. In Piwik you can take notes on the graph and set any number of text messages. They’re called Annotations (click to learn more).

How do I customise the JavaScript Tracker code on all websites at once?

To measure your websites with Piwik you are likely to use the Piwik JavaScript Tracking code, a small snippet of code that should be added in your websites pages. When visitors view your website, the Piwik tracking code gets executed by the browser and your visitor’s browsers load the piwik.js file from your Piwik server, for example:

In some cases it may be useful to customise the piwik.js tracking code. This FAQ explains the best practise method to let you safely edit the piwik.js file. Note that this is an advanced feature and should be used with great care. First you will need to install and activate the plugin CustomTrackerJs. Login as a Super User in Piwik then go to Administration, click on Marketplace and install the plugin CustomTrackerJs. After activating this plugin, Super User can click on the Admin menu ‘Plugin Settings’ link. Any text entered in the field ‘Javascript code’ will be appended to the content of piwik.js.

For example, if you wanted to enable Content Tracking on all your websites at once, enter the following:

if ('undefined' !== typeof _paq) {

Note: changing piwik.js will affect all your websites at once (all websites load the same piwik.js file). Use this feature with care: if you input invalid JavaScript code then it may create JavaScript errors on your websites.

How do I verify the cryptographic PGP signature of Piwik packages?

When we create a new Piwik release, right after the Piwik core packages .zip and .tar.gz have been created, the Piwik release manager signs the packages using his PGP key. This creates a cryptographic signature which gives you the possibility to check that the release package you have downloaded is the same as the one that was provided by Piwik team. Learn how to verify the signature in this blog post with instructions for Windows, Mac OS X and Linux.

How do I get the Visitor Geo Location data from the Visitor IP?

In Piwik we recommend to configure Geo Location so that your visitors are accurately tracked. Once it is setup, you can use the GeoIP database to get an IP to Country, or IP to City, or IP to Region information. We have added a simple API that you can re-use, called UserCountry.getLocationFromIP.

To use it, go to Piwik, click API, click on “UserCountry” then on the getLocationFromIp call.

Click to see typical response from the API.

You may use this simple Web API provided by Piwik to add geo location functionality to your Apps, for example.

How do I disable the update notification email when a new Piwik version is released?

At Piwik we have a policy to recommend users to use the very latest Piwik version. To help you with keeping up to date with the latest version, your Piwik server will automatically send you an email within a day after a new version was published. The subject email is New Piwik 3.0.0 is available and the message contains a direct link to your Piwik to update in one click. The email is only sent to users having Super User access.

If for some reasons you do not want your Piwik server to send these notification emails you can disable them by editing your config/config.ini.php file and adding below [General] the following: enable_update_communication=0

Note: this setting will also disable the New Plugin releases notifications emails. Plugin notifications is a feature you can enable in ‘General Settings’ that will send Super Users an email when a new plugin versions is released on the Marketplace.

How do I access a real time counter of visitors currently on my site?

On the Piwik dashboard you may add the widget “Real time > Real time visitor count”. This widget shows a counter of the number of people currently on the website.
By default Piwik uses a 3 minutes delay to define a “Visitor currently on the website”. You may edit this value in the config.ini.php file, for example set to 10 minutes:


How do I create Custom Segments of Visitors and apply the segments to filter my report’s data?

Piwik lets you easily create advanced Custom Segments of Visitors. You can save Custom Segments to reuse them later. As well as being available from the User Interface, Custom Segments can also be applied via the Analytics API. Custom Segments can contain unlimited number of AND and OR clauses, using any combination of more than 40 available dimensions (visitor attributes).

Note: you may also apply custom segments to Custom reports scheduled to be sent by sms text message and/or email reports as HTML or PDF. With Piwik you can scheduled reports on a custom segment of your audience, better analytics for your team members and clients.

How do I monitor that Piwik service is up and running?

To setup monitoring of your Piwik analytics service, we recommend to setup the following monitoring checks:

  • HTTP Reporting API and Core platform: request to /index.php?module=API&method=API.getPiwikVersion&token_auth=YOUR_TOKEN_AUTH_HERE should return http status 200
  • HTTP Tracker API: request to /piwik.php should return http status code 200

We recommend to use https:// in the monitoring URLs checks, to make sure that your Piwik service works over secured connection.

How do I configure Piwik Tracking for high reliability?

To configure Piwik Tracking for high availability, reliability, and better scalability, please see this other FAQ: How do I configure Piwik to use Redis for better scalability?

Note: if you need professional support, get in touch with the Piwik consultants who are experts in scaling and configuring Piwik.

Related user guides: learn more about Piwik performance, and read tips how to optimize Piwik for speed. You may also be interested in Data Limits.

How do I configure Piwik to use Redis for better scalability?

When you track a lot of data in your Piwik server, you may find that the calls to the Tracking API (piwik.php) become a scalability bottleneck. At Piwik PRO we have created a new plugin QueuedTracking for the Piwik Cloud that we also give away for free(dom) to you, the community. This plugin will help with scaling your Piwik server to track dozens or hundreds of millions of requests per month.

This plugin writes all tracking requests into a Redis instance instead of directly into the database. This is useful if you have too many requests per second and your server cannot handle all of them directly (eg too many connections in nginx or MySQL). It is also useful if you experience peaks sometimes. Those peaks can be handled much better by using this queue. Writing a tracking request into the queue is very fast (a tracking request takes in total a few milliseconds) compared to a regular tracking request (that takes multiple hundreds of milliseconds). The queue makes sure to process the tracking requests whenever possible even if it takes a while to process all requests after there was a peak.

To get started, install the QueuedTracking plugin from the Marketplace. Click on the FAQ tab to learn more about the requirements and how to use the plugin on your Production Piwik server. For any bug report or feature request, please post them in the plugin’s issue tracker.

Contact Piwik PRO if you need help with high traffic Piwik setup, or if you’d like experts to take care of your Piwik setup, configuration, maintenance and security.

How to configure Redis as a shared cache in a load balanced environment?

By default Piwik caches data in the local filesystem of each server. If your Piwik environment consists of multiple servers a common problem is that caches are only invalidated on one server instead of all servers. To workaround this we recommend to use a shared cache for all of your servers. You can do this by installing and configuring Redis.

To use Redis as a cache follow these steps:

  • Make sure you are using at least Piwik 2.10 (latest Piwik version recommended)
  • Install Redis see Redis Quickstart
  • Install the PHP extension phpredis
  • Don’t forget to restart your webserver
  • Once successfully setup, enable it in the config file config/config.ini.php. Make sure to adjust the section [RedisCache] to your needs. You have to make this change on each of your server.

changes to config/config.ini.php:

backend = chained

backends[] = array
backends[] = redis

host = "" 
port = 6379
timeout = 0.0
password = ""
database = 14
; In case you are using queued tracking: Make sure to configure a different database! Otherwise queued requests will be flushed

How do I configure Redis for session handling in a load balanced environment?

By default Piwik uses the filesystem as a session handler. If your Piwik environment consists of multiple servers a common problem is that multiple sessions are created per user meaning a user might have to log in multiple times and a log out might actually log out a user only on one server. To workaround this there are two options:

To use Redis as a session handler follow these steps:

  • Install Redis see Redis Quickstart
  • Install the PHP extension phpredis
  • Configure Redis as PHP session handler in php.ini on each of your server.

In php.ini:

session.save_handler = redis 
session.save_path    = tcp://
; In case you are using queued tracking or Redis as a cache: Make sure to configure a different database! Otherwise queued requests will be flushed

; multiple servers can be configured comma separated
session.save_path = "tcp://host1:6379?weight=1&database=2, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2"

See Redis Session Handler for more documentation.

  • Don’t forget to restart your webserver
  • Once successfully setup, make sure there is no Piwik default session handler configured by setting the session_save_handler to an empty value in the config file config/config.ini.php. Youconfig/config.ini.php have to make this change on each of your server.

In config/config.ini.php:

session_save_handler = ""

How do I submit a feature request for Piwik?

We appreciate you taking the time to explain how we can improve Piwik!

If you realize that there is something you need that is missing in Piwik, please submit a feature request to Piwik.

See also: How do I report a bug in Piwik?

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: