Matomo packages for Debian

This is the Matomo project's own repository. It is not part of the Debian archive, and the package it provides is not the one Debian distributes. Both exist; they no longer share a name.

Installing Matomo for the first time

Debian 12 or 13, a web server with PHP, a MariaDB or MySQL server. Then:

sudo apt install apt-transport-https curl
sudo curl -fsSLo /usr/share/keyrings/matomo-archive-keyring.gpg \
     https://debian.matomo.org/repository.gpg
echo "deb [signed-by=/usr/share/keyrings/matomo-archive-keyring.gpg] \
https://debian.matomo.org/ matomo-vanilla main" \
  | sudo tee /etc/apt/sources.list.d/matomo-vanilla.list
sudo apt update
sudo apt install matomo-vanilla

The package asks three questions.

1. May it migrate the database for you at each upgrade? Say yes unless you want to run core:update yourself.
2. Enable the archiving timer now? Archiving, in Matomo's vocabulary, is the computing of the reports: the raw visits the tracker records are aggregated into the figures the dashboards show, per site and per period. Left to itself Matomo does that when someone opens a report, which is slow on a busy site; the timer runs it once an hour in the background. Yes is safe even now: a run with nothing configured is skipped, and archiving begins by itself once you finish the web installer. Matomo's own advice, once a scheduled run is in place, is to switch off browser-triggered archiving under Administration → System → General settings.
3. Serve Matomo at /matomo on every site of this web server? Asked on a fresh installation only, never over an installed Matomo or an alias already in service. Declined by default, and the question says why: until you have completed the web installer, that address shows the installer's welcome page to anyone who can reach the server, and lets them run it, administrator account included. Say yes on a machine that is not reachable from the Internet, or when you are about to complete the installer right away. Otherwise decline and give Matomo a virtual host of its own.

What the package has done with the web server, whatever you answered:

Then open it in a browser and finish the installation there. /usr/share/doc/matomo-vanilla/README.Debian covers the database, the virtual host and the ownership of the tree.

Verifying the key before trusting it is covered under The signing key. The suite is matomo-vanilla; the older matomo suite only carries the last package under the old name. Nothing else on this page is needed for a first installation.

Two packages: matomo-vanilla here, matomo at Debian

Debian ships matomo. This repository ships matomo-vanilla. They install into the same directory, so you can only have one.

Debian's package is the better choice if you want someone else carrying the security burden and can live on the version your distribution shipped — install it from Debian, not from here. Note what that means today: Debian 13 carries Matomo 5.3.1 from early 2025, upstream is at 5.14.1, and upstream has published around forty changelog entries marked Security in between. None of Debian's patches is a security fix, and those fixes are in Matomo's own code rather than in the libraries that were substituted.

This repository's package is the better choice if you want current Matomo.

What matomo-vanilla contains, file by file

Of the 11 887 files in upstream's 5.14.1 release, every one is shipped byte for byte. One file is added, bootstrap.php, upstream's own documented hook. It tells Matomo to keep everything this installation writes outside the code tree: the configuration (/etc/matomo), caches and uploads, extensions installed from the Marketplace, and the GeoIP 2 / DB-IP databases Matomo downloads for itself, all under /var/lib/matomo. Nothing in /usr/share/matomo is writable by the web server, and upstream's integrity manifest ships exactly as written, so Matomo's System Check agrees with what is on disk. Two symlinks are added for Matomo's own benefit: plugins-ext, so that an extension's assets stay reachable, and tmp, pointing at the real cache directory, so that Matomo's "private directories" check tests the right place.

Around that, the integration: a systemd timer, a web server snippet, the database migration run for you, and an apt channel that keeps up. That is what this repository has always been for; the name now says what the contents are.

Upgrading from this repository's old matomo package to matomo-vanilla

If you installed matomo from this repository — the last version published under that name is 5.3.1-1, from March 2025 — the move to matomo-vanilla takes two steps, and both are yours to take. No upgrade makes the switch for you.

Step 1 — apt upgrade brings the announcement, and nothing else

The first thing apt offers you is one more version of matomo, 1:5.3.1-2, that changes nothing at all: the same Matomo, the same files, one notice added. Take it; it is an ordinary upgrade, apt upgrade or apt-get upgrade alike. Before anything is unpacked, the notice opens in a pager and says what this page says. From then on, apt prints a short reminder after each run, until you make the switch or tell it you have read enough:

sudo touch /etc/matomo/rename-notice-acknowledged

On Debian 13 the announcement cannot reach you by itself: apt has been refusing this repository's old signing key since early 2026. Start with the key, point your existing matomo sources line at it with signed-by=, run apt update, and the announcement is there.

Step 2 — install the new key, then apt install matomo-vanilla

matomo-vanilla lives in a suite of its own, matomo-vanilla, signed by a key the old package did not give you. Install the keyring file and add the sources line, both as in the installation block above; your existing line for the matomo suite can stay, nothing more will come through it. Then ask for the package by name:

sudo apt install matomo-vanilla

As a precaution before that, and it is your call, keep a copy of your configuration and of your database; the switch keeps both where they are, and the copy costs a minute:

sudo tar czf ~/matomo-before-vanilla.tar.gz /etc/matomo
mysqldump --single-transaction <database> > ~/matomo-before-vanilla.sql

It replaces the matomo package. Your configuration in /etc/matomo, your data in /var/lib/matomo and your database stay where they are, and the step that migrates the database announces itself before it starts. Ctrl+C is safe there: the package catches the signal, prints the command that resumes, and Matomo records each migration step as it completes, so a retry picks up where it stopped. Take a backup first if you have not got one; the migration is not reversible.

sudo dpkg --configure matomo-vanilla     # to resume, or: sudo apt-get install -f

If an archiving cron job of yours was active, the package asks whether to keep it or to hand over to the timer; handing over comments the cron line out, so the two do not both archive. If you relied on /var/log/matomo/matomo-archive.log, add the package that writes it:

sudo apt install matomo-vanilla-logfile

What is left of the old package is its record and its configuration files, which no longer do anything. Once Matomo answers correctly:

sudo apt purge matomo

If Matomo's own updater has replaced the code: the announcement refuses, and says what to do

Then the code in /usr/share/matomo is newer than the 5.3.1 that dpkg recorded, and the announcement refuses to install rather than put 5.3.1 back in front of a database migrated further. The refusal lists every command of the way out; in short, check that the version packaged here is not behind the Matomo you are running, back up the database, set the tree aside, purge the old package, install matomo-vanilla, and copy back any extension you had installed:

sudo apt update && apt policy matomo-vanilla
mysqldump --single-transaction <database> > ~/matomo-before-vanilla.sql
sudo mv /usr/share/matomo /usr/share/matomo.updated-in-place
sudo apt purge matomo
sudo apt install matomo-vanilla
sudo cp -a /usr/share/matomo.updated-in-place/plugins/<Name> /var/lib/matomo/plugins/
sudo chown -R www-data:www-data /var/lib/matomo/plugins

Until you do, every apt upgrade ends on that refusal. To put it off instead: sudo apt-mark hold matomo.

Why the switch is left to you

Because the switch has to be deliberate. Debian 13 carries its own matomo at 5.3.1+dfsg-1, which dpkg reads as newer than the 5.3.1-1 published here: a machine that moved from Debian 12 to 13 while still on the old package has had its Matomo quietly replaced by Debian's during the release upgrade. Distinct names end that, and a new name is one apt never installs on its own. The announcement makes sure you are told; the key makes sure the package you then install is this one.

Updating Matomo afterwards: through apt, or through Matomo's own updater

Either apt or Matomo itself can be in charge of the code, not both. The package ships with Matomo's own updater off; which one is in charge is your decision, and reversible.

Through apt, the default: what each version has been through

sudo apt update
sudo apt upgrade

Every version is checked before it reaches you, and this is the part an in-place update cannot reproduce: the archive's detached GPG signature is verified against a pinned fingerprint at build time, lintian runs on the finished package, piuparts installs and purges it in a clean chroot on Debian 12 and 13, the upgrade from the previous published version is replayed against a real database on both, and the files belong to root, so the web server cannot rewrite the code it runs.

Letting Matomo update itself: two steps, and what you give up

Two steps, and both are needed; the setting alone does nothing:

# 1. the setting, in your own file
sudo sed -i 's/^enable_auto_update *=.*/enable_auto_update = 1/' /etc/matomo/config.ini.php

# 2. the permission, without which step 1 has no effect
sudo chown -R www-data:www-data /usr/share/matomo

You then get a release the day it ships, rather than the day it is packaged here. Your configuration, extensions and GeoIP databases are outside the tree Matomo overwrites, so they are not disturbed, and bootstrap.php survives the overwrite too, upstream's archive not containing it.

The package's own default lives in /etc/matomo/common.config.ini.php, which sets enable_auto_update = 0. Matomo merges that file before config.ini.php, so your setting wins. Leave the package's file alone and put your line in yours.

Handing the code back to apt afterwards

By then Matomo has replaced the files and dpkg no longer recognises them, so the package refuses to install over the tree and says so. Three commands, the middle one being the whole operation:

sudo sed -i 's/^enable_auto_update *=.*/enable_auto_update = 0/' /etc/matomo/config.ini.php
sudo mv /usr/share/matomo /usr/share/matomo.updated-in-place
sudo apt install --reinstall matomo-vanilla

Nothing of yours is in that tree: configuration, database, extensions and GeoIP databases stay where they are. One caveat: do not hand the code back to a package older than the Matomo that has been running (apt policy matomo-vanilla); wait for it to catch up. Your site is down between the second and third command, so pick your moment.

Extensions from the Marketplace, and where they live

Installing from the Marketplace works and needs nothing from you. The Marketplace writes into /var/lib/matomo/plugins, owned by www-data, the one place the web server may write code; /usr/share/matomo/plugins holds what upstream bundles and stays root's. Matomo loads from both. Extensions installed under the old matomo package sit in the code tree, where its Marketplace put them, and are left there by the switch; only setting the tree aside moves them, and copying them to /var/lib/matomo/plugins brings them back enabled.

If Debian's matomo package is installed: no upgrade path, in either direction

There is no upgrade path, and nothing here will install over it. If this repository is in your sources, the announcement is offered to you as an upgrade of matomo and refuses before touching anything, naming what it found; so does matomo-vanilla:

* STOPPING. Nothing on this system has been changed.

  The matomo package installed here, version 5.3.1+dfsg-1, is not from
  debian.matomo.org: it is the one Debian distributes.

If Debian's package is the one you want, take this repository out of your apt sources, or hold the package: sudo apt-mark hold matomo. If you want this repository's Matomo instead, that is a switch, not an upgrade, and it is yours to drive, at your own risk: keep a copy of your database and of your configuration file, remove Debian's package (sudo apt remove --purge matomo), install matomo-vanilla, put your configuration file into /etc/matomo and point it at your database. Reattaching an older database to newer code is the part that can go wrong, and none of it is tested here.

The other way round, sudo apt install matomo on a machine running matomo-vanilla, is refused as well, whichever of the two repositories answers: the announcement stops when it finds matomo-vanilla, and Debian's package is stopped by dpkg for owning the same files. Nothing is removed in either case.

Report archiving: the hourly timer, its scope, and where its output goes

Report archiving is a systemd timer, matomo.timer, and the package asks whether to enable it rather than leaving you to remember. Which question it asks depends on what it finds already running:

sudo dpkg-reconfigure matomo-vanilla           # to be asked again
sudo systemctl enable --now matomo.timer       # or disable --now

The timer archives every site, which is what core:archive does on its own. Anything finer is a drop-in of your own, with upstream's options — --force-idsites=, --skip-idsites=, --skip-all-segments, --url=:

sudo systemctl edit matomo.service

[Service]
ExecStart=
ExecStart=/usr/bin/php /usr/share/matomo/console core:archive --force-idsites=1,4

Clearing ExecStart first is required; without the empty assignment your line is added to the existing one rather than replacing it.

The run's output goes to the journal: journalctl -u matomo, already rotated and size-capped. If you want the file the old package wrote, /var/log/matomo/matomo-archive.log, rotated daily, one package adds it alongside the journal and removing it puts the service back as it was:

sudo apt install matomo-vanilla-logfile
sudo apt purge matomo-vanilla-logfile

If your own drop-in sets ExecStart, yours wins and the file stops being written; the line to copy into yours is in /usr/lib/systemd/system/matomo.service.d/10-logfile.conf.

The repository signing key: what changed, how to verify it

# what your machine already has, if the old package is installed
gpg --show-keys /etc/apt/trusted.gpg.d/matomo-keyring-automatic.gpg

# the refreshed key
curl -fsSL https://debian.matomo.org/repository.gpg | gpg --show-keys

Same fingerprint on both sides means it is the same key, and nothing new is being asked of your trust; the file from the site simply carries the signing subkey as well. Expected checksum of the key file:

The keyring goes in /usr/share/keyrings/ and is named in the sources line with signed-by=, so that it is trusted for this repository alone. The old package put its key in /etc/apt/trusted.gpg.d/, trusted for every repository; purging that package removes it.