Debian 10 – PHP / Matomo GeoIP2 Installation

The old GeoIP legacy release (aka. GeoIPCity.dat) has been deprecated and doesn’t receive updates for quit some time. It will get removed from Matomo with the next major release.
If you would like to have accurate location detection in Matomo / Piwik the new GeoIP2 module should be used.

Since Debian Buster doesn’t ship it with it’s PHP packages, there are some manual steps needed to achieve that.

Location/City detection

First of all install the needed library, build-tools and the php-dev package in order to be able to build the maxminddb PHP extension.

apt-get install libmaxminddb-dev php-dev git build-essential

Next step is to clone the MaxMind-DB-Reader-php repository in order to compile the PHP module.

cd /usr/local/src
git clone
cd MaxMind-DB-Reader-php/ext
make && make install

After that the new PHP module needs to be enabled and Apache or PHP (when using FPM) restarted:

echo "" > /etc/php/7.3/mods-available/maxminddb.ini
phpenmod maxminddb

# The folder /usr/share/GeoIP needs to be added
# to the PHP open_basedir setting in your php.ini

apache2ctl graceful
service php7.3-fpm restart

Now the database GeoIP2-City.mmdb needs to be installed locally. Since the free version is updated once a month, this is done via a download cronjob.
The database is provided by DB-IP (thanks). Check their website for usage conditions.

apt-get install python3-requests

mkdir -p /usr/share/GeoIP

cat >> /usr/local/sbin/ << EOF
#!/usr/bin/env python3
import requests
import datetime
import gzip
import sys

url = ''
now =
date = now.strftime('%Y-%m')
dbs = {
  'GeoIP2-City': {
    'output_file': '/usr/share/GeoIP/GeoIP2-City.mmdb',
    'download_file': 'dbip-city-lite-{}.mmdb.gz'.format(date)

for db in dbs:
  r = requests.get(url + dbs[db]['download_file'])
  if r.status_code ==
    with open(dbs[db]['output_file'], 'wb') as f:
    print('Download failed for {}: '.format(db) + str(r.status_code))

chmod 700 /usr/local/sbin/

cat >> /etc/cron.d/geoip2-update << EOF
0 7 28 * *     root  /usr/local/sbin/

Now the GeoIP2 database gets updated once a month automatically and the script should be executed once to get the current version right now and to test the setup as well.


In order to use GeoIP2 in Matomo two settings need to be done. First of all a database Symlink needs to be created in order to use the GeoIP2 database in Matomo.

# adjust path to your matomo misc folder
ln -s /usr/share/GeoIP/GeoIP2-City.mmdb /var/www/matomo/misc/

After that the Plugin GeoIp2 needs to be activated. It’s a core package and should be already listed on the Matomo Plugins page in the Admin UI.

Now it should be possible to activate the new module under Geolocation. If your location is listed on the right side, enable the GeoIP2 box and click Save.

That’s it. The results are much more accurate and quicker. (If you want ISP detection as well check the last section of this post.)


If you don’t use Matomo a PHP GeoIP2 testscript could be used instead.


use MaxMind\Db\Reader;
$reader = new Reader('/usr/share/GeoIP/GeoIP2-City.mmdb');
$record = $reader->get($_SERVER['REMOTE_ADDR']);

print($record['continent']['names']['en'] . "\n");
print($record['country']['names']['en'] . "\n");
print($record['subdivisions'][0]['names']['en'] . "\n");
print($record['city']['names']['en'] . "\n");


Your continent, country, subdivision and city should be listed after executing the script via the webserver.

ISP detection

If you want to have ISP detection as well, you need to download the GeoLite2-ASN.mmdb database or an commercial alternative (either from Maxmind or from DB-IP). There is also a guy hosting the free Maxmind version on GitHub, but since I’m not sure if this is a proper version I will not link it. The official way is to create an Maxmind account and download it from there.
Unfortunately the free DB-IP ASN database isn’t supported in Matomo until this patch is rolled out in version 4.x.

After the database is downloaded and stored in /usr/share/GeoIP it needs to be linked as well.

# adjust path to your matomo misc folder
ln -s /usr/share/GeoIP/GeoLite2-ASN.mmdb /var/www/matomo/misc/

Schreibe einen Kommentar