How to Install Matomo with Nginx on Ubuntu (26.04, 24.04, 22.04)

Matomo gives you page views, goals, campaigns, and ecommerce reporting without handing that data to a third-party analytics provider. You can install Matomo on Ubuntu with Nginx, MariaDB, and PHP-FPM, then finish the browser installer on your own domain or on a private host before exposing it to the internet.

Ubuntu 26.04, 24.04, and 22.04 all support this stack from the default repositories, while Matomo itself comes from the official tarball instead of an Ubuntu package. The commands stay the same across all three LTS releases, but the PHP-FPM socket name changes with the default PHP branch.

Install Matomo on Ubuntu

This workflow uses Ubuntu’s default Nginx, MariaDB, and PHP-FPM packages, then adds Matomo from the official upstream archive. Matomo’s current requirements page still recommends PHP 8.x and MySQL 8+ or MariaDB, so all three supported Ubuntu LTS releases meet the server baseline.

Ubuntu release	Default PHP-FPM	Default MariaDB	Matomo note
Ubuntu 26.04 LTS	PHP 8.5.x (php8.5-fpm)	MariaDB 11.8.x	Use the 8.5 PHP-FPM socket in Nginx
Ubuntu 24.04 LTS	PHP 8.3.x (php8.3-fpm)	MariaDB 10.11.x	Use the 8.3 PHP-FPM socket in Nginx
Ubuntu 22.04 LTS	PHP 8.1.x (php8.1-fpm)	MariaDB 10.6.x	Use the 8.1 PHP-FPM socket in Nginx

Matomo does not publish an official Ubuntu .deb package for this setup. The supported self-hosted path here uses the upstream matomo-latest.tar.gz archive, then serves it through Ubuntu’s own Nginx, MariaDB, and PHP-FPM packages.

Update Ubuntu and install Nginx for Matomo

Start with current package metadata, then install Nginx plus the download tools used later in the tarball workflow.

sudo apt update && sudo apt upgrade -y

These commands use sudo because they change system packages and service state. If your account does not have sudo access yet, first add a new user to sudoers on Ubuntu.

sudo apt install nginx wget unzip curl -y

Confirm that Nginx started cleanly before you move on:

systemctl status nginx --no-pager

A healthy service looks like this:

● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-03-20 08:57:44 AWST; 2min 35s ago
 Invocation: 32df97507eec4b1e968481871411353a
       Docs: man:nginx(8)
   Main PID: 23874 (nginx)

If UFW is enabled on this server, allow the web ports before you open the installer with sudo ufw allow 'Nginx Full'. For SSH planning, custom application rules, and cleanup, configure UFW on Ubuntu first.

Ubuntu’s default Nginx package is enough for Matomo. If this host also needs the newer branch for other sites, use the separate guide to install Nginx Mainline on Ubuntu.

Install MariaDB for Matomo on Ubuntu

Matomo stores visits, reports, goals, and other analytics data in a MySQL-compatible database. MariaDB works out of the box on Ubuntu and stays in the supported range across 26.04, 24.04, and 22.04.

sudo apt install mariadb-server mariadb-client -y

Check that the database service is running:

systemctl status mariadb --no-pager

You should see an active MariaDB service:

● mariadb.service - MariaDB 11.8.6 database server
     Loaded: loaded (/usr/lib/systemd/system/mariadb.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-03-20 08:55:06 AWST; 5min ago
 Invocation: b5bb377a2db1412fbf19ffb2b6a60307
       Docs: man:mariadbd(8)
             https://mariadb.com/kb/en/library/systemd/

Before you create the Matomo database, run the MariaDB hardening script:

sudo mariadb-secure-installation

Use the script to remove anonymous users, block remote root logins, drop the test database, and reload the privilege tables. Some Ubuntu releases still provide mysql_secure_installation as a compatibility alias, but mariadb-secure-installation matches the current package naming. If you need different MariaDB branches or deeper hardening, see Install MariaDB on Ubuntu.

Install PHP-FPM and Matomo extensions on Ubuntu

Keep this as an FPM-first install. On Ubuntu, the plain php metapackage can satisfy its dependency with Apache’s module instead of PHP-FPM, so this Nginx guide installs the FPM and extension packages directly.

sudo apt install php-fpm php-cli php-mysql php-gd php-curl php-xml php-mbstring php-bcmath php-intl php-zip php-imagick php-ldap -y

Verify the active PHP branch:

php -v

On Ubuntu 26.04 the first line looks like this:

PHP 8.5.2 (cli) (built: Jan 21 2026 17:35:28) (NTS)

Now confirm the matching PHP-FPM service. Replace the service name if you are on Ubuntu 24.04 or 22.04:

systemctl status php8.5-fpm --no-pager

A working PHP-FPM service looks like this:

● php8.5-fpm.service - The PHP 8.5 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php8.5-fpm.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-03-20 08:55:17 AWST; 5min ago
 Invocation: ef90806f50cd4750825c16ee5c30e423
       Docs: man:php-fpm8.5(8)
   Main PID: 20818 (php-fpm8.5)

Matomo’s requirements center on PHP 8.x plus database, graphics, XML, and multibyte support, which this package set covers. If you need another PHP branch for a different site on the same host, use Install PHP on Ubuntu for the broader version-management workflow.

Download and extract Matomo on Ubuntu

Matomo’s supported self-hosted install uses the official archive. The download itself is simple, and wget command examples covers resume, output-file, and mirror options if you need them on a slower link.

cd /tmp && wget https://builds.matomo.org/matomo-latest.tar.gz

Make sure the archive was saved before you extract it:

ls -lh /tmp/matomo-latest.tar.gz

The file check should look similar to this:

-rw-rw-r-- 1 linuxcapable linuxcapable 22M Mar  5 06:35 /tmp/matomo-latest.tar.gz

Extract Matomo into its own web root. The --strip-components=1 option removes the top-level archive directory so the application lands directly in /var/www/matomo:

sudo mkdir -p /var/www/matomo
sudo tar -xzf /tmp/matomo-latest.tar.gz -C /var/www/matomo --strip-components=1

Check that the expected Matomo files exist:

ls /var/www/matomo

A successful extract includes the main application tree:

CHANGELOG.md
config
console
core
index.php
js
matomo.php
plugins
tmp
vendor

Now hand the tree to the web-server user and apply standard directory and file modes. The two find ... -exec chmod commands keep directories traversable while regular files stay read-only by default. For a deeper breakdown of 755 and 644, see this chmod command guide.

sudo chown -R www-data:www-data /var/www/matomo
sudo find /var/www/matomo -type d -exec chmod 755 {} \;
sudo find /var/www/matomo -type f -exec chmod 644 {} \;

Verify the key writable directories now belong to www-data:

sudo ls -ld /var/www/matomo /var/www/matomo/config /var/www/matomo/tmp

You should see ownership like this:

drwxr-xr-x 13 www-data www-data 4096 Mar 20 08:57 /var/www/matomo
drwxr-xr-x  3 www-data www-data 4096 Mar 20 08:58 /var/www/matomo/config
drwxr-xr-x  8 www-data www-data 4096 Mar 20 08:58 /var/www/matomo/tmp

Create the Matomo Nginx server block on Ubuntu

Put the Matomo Nginx configuration in /etc/nginx/sites-available/matomo.conf, then enable it from /etc/nginx/sites-enabled/. This server block is adapted from Matomo’s official Nginx configuration repository, but trimmed for Ubuntu’s packaging and this HTTP-first install flow.

sudo nano /etc/nginx/sites-available/matomo.conf

Use the PHP-FPM socket that matches your Ubuntu release: /run/php/php8.5-fpm.sock on 26.04, /run/php/php8.3-fpm.sock on 24.04, and /run/php/php8.1-fpm.sock on 22.04. Ubuntu’s snippets/fastcgi-php.conf already carries its own try_files rule, so do not paste a second try_files $fastcgi_script_name =404; line into this server block or nginx -t will fail with a duplicate-directive error.

server {
    listen 80;
    listen [::]:80;
    server_name matomo.example.com;

    root /var/www/matomo;
    index index.php;

    access_log /var/log/nginx/matomo.access.log;
    error_log /var/log/nginx/matomo.error.log;

    location ~ ^/(index|matomo|piwik|js/index|plugins/HeatmapSessionRecording/configs)\.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_param HTTP_PROXY "";
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
    }

    location ~* ^.+\.php$ {
        deny all;
        return 403;
    }

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ ^/(config|tmp|core|lang) {
        deny all;
        return 403;
    }

    location ~ /\.ht {
        deny all;
        return 403;
    }

    location ~ js/container_.*_preview\.js$ {
        expires off;
        add_header Cache-Control "private, no-cache, no-store";
    }

    location ~ \.(gif|ico|jpg|png|svg|js|css|htm|html|mp3|mp4|wav|ogg|avi|ttf|eot|woff|woff2|json)$ {
        allow all;
        expires 1h;
        add_header Pragma public;
        add_header Cache-Control "public";
    }

    location ~ ^/(libs|vendor|plugins|misc|node_modules) {
        deny all;
        return 403;
    }

    location ~ /(.*\.md|LEGALNOTICE|LICENSE) {
        default_type text/plain;
    }
}

Enable the site, remove Ubuntu’s default placeholder site if it is still active, test the syntax, and restart Nginx:

sudo ln -s /etc/nginx/sites-available/matomo.conf /etc/nginx/sites-enabled/matomo.conf
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx

A clean syntax check looks like this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

This server block starts on port 80, which is enough to reach the installer before TLS is in place. Before you leave the shell, verify that Nginx can reach the Matomo installer locally. This is a quick way to catch bad socket paths or missing files before you switch to the browser.

curl -I -H "Host: matomo.example.com" http://127.0.0.1/

A healthy local response starts like this:

HTTP/1.1 200 OK
Server: nginx/1.28.2 (Ubuntu)
Date: Fri, 20 Mar 2026 00:58:19 GMT
Content-Type: text/html; charset=utf-8
Connection: keep-alive
X-Matomo-Request-Id: 45ba1

If you want more header and redirect checks from the shell, see curl command in Linux. If this Matomo host will sit behind another frontend proxy or load balancer, adapt the final topology with Create a reverse proxy in Nginx.

Create the Matomo database and user on Ubuntu

Matomo should use its own database and login instead of borrowing MariaDB’s administrative account.

sudo mariadb

Run these SQL statements inside the MariaDB shell. Replace the example password before you continue:

CREATE DATABASE matomo_db;
CREATE USER 'matomo_user'@'localhost' IDENTIFIED BY 'ChangeThisStrongPassword!';
GRANT ALL PRIVILEGES ON matomo_db.* TO 'matomo_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Confirm the account has the expected grant on the Matomo database:

sudo mariadb -e "SHOW GRANTS FOR 'matomo_user'@'localhost';"

The grant check should include the Matomo database permission:

Grants for matomo_user@localhost
GRANT USAGE ON *.* TO `matomo_user`@`localhost` IDENTIFIED BY PASSWORD '*E8266F4F0C0EF64732AAFC4F13321F3BA61A5FF0'
GRANT ALL PRIVILEGES ON `matomo_db`.* TO `matomo_user`@`localhost`

Complete the Matomo web installer on Ubuntu

Open the hostname you used in server_name and walk through the browser installer. A private IP, internal DNS name, or temporary hosts-file entry is fine while you validate the stack; you only need a public hostname later if you want Let’s Encrypt to issue a certificate.

Open the Matomo installer in a browser

The first page confirms that Matomo is serving correctly through Nginx:

The installer also runs a quick environment check for PHP, extensions, file permissions, and database drivers. Fix any red entries in the shell before you continue:

• PHP version and required extensions
• Writable Matomo directories such as config and tmp
• Database driver availability for MariaDB
• General server environment compatibility

Connect Matomo to MariaDB and create the admin account

Use the database name, username, and password you created in the shell. For a local database server, the host field usually stays at localhost:

• Database Server: localhost
• Login: matomo_user
• Password: the password you assigned to matomo_user
• Database Name: matomo_db

After the database step, create the first Matomo super user account. This is the main administrative login for reports, plugins, and site settings:

• Username: choose a dedicated admin name
• Password: use a strong password you do not reuse elsewhere
• Email Address: use a working address for account recovery and alerts

Add the first website and tracking code in Matomo

Once the admin account exists, add the first site you want Matomo to track and copy the JavaScript snippet it generates:

• Website Name: the site label you want to see in reports
• Website URL: the full canonical URL of the site you are tracking

Place the tracking snippet in the HTML of the site you want to measure, usually just before the closing </head> tag:

After you finish the wizard, Matomo opens the dashboard and waits for the first tracked visits:

Secure Matomo on Ubuntu with Let’s Encrypt

Use HTTPS once the Matomo hostname resolves publicly to this server. If you are still testing through localhost, a private IP, or temporary DNS, skip this section for now and come back after the final hostname is live.

Install Certbot for Matomo on Ubuntu

Ubuntu packages the Nginx Certbot plugin directly:

sudo apt install python3-certbot-nginx -y

For more examples around redirect choices, wildcard edge cases, and renewal debugging, follow Secure Nginx with Let’s Encrypt on Ubuntu.

Request a Let’s Encrypt certificate for Matomo on Ubuntu

Replace the email address and hostname with the values that match your deployment:

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email admin@example.com -d matomo.example.com

The important flags here are --redirect for automatic HTTP to HTTPS redirects, --hsts for strict transport security, and --staple-ocsp for OCSP stapling.

Verify the Certbot renewal timer on Ubuntu

Ubuntu’s Certbot package installs a systemd timer for automatic renewal. Check that it is active:

systemctl status certbot.timer --no-pager

A working renewal timer looks like this:

● certbot.timer - Run certbot twice daily
     Loaded: loaded (/usr/lib/systemd/system/certbot.timer; enabled; preset: enabled)
     Active: active (waiting) since Fri 2026-03-20 09:00:12 AWST; 1s ago
 Invocation: 74182ea9a3f04721a9ea3fcdb6c4c3e8
    Trigger: Fri 2026-03-20 12:57:54 AWST; 3h 57min left
   Triggers: ● certbot.service

Configure Matomo archiving on Ubuntu

Matomo’s scheduled archiver keeps reports fast by pre-processing data instead of building every report on demand in the browser. The upstream archiving guide uses the Matomo CLI with a matching base URL, so wait until the installer is complete and you know the final HTTP or HTTPS address you want the archiver to use.

Create the Matomo archiver cron job on Ubuntu

Edit the www-data crontab so the archiver runs as the same account that owns the Matomo files:

sudo crontab -e -u www-data

Add this line, replacing the URL with your real Matomo address. If you enabled HTTPS already, keep the https:// URL here as well:

5 * * * * /usr/bin/php /var/www/matomo/console core:archive --url=https://matomo.example.com/ >> /var/log/matomo-archive.log 2>&1

The --url= value tells Matomo which base URL to use while it builds reports, and the log file gives you something concrete to inspect if archiving falls behind.

List the cron entry after you save it:

sudo crontab -l -u www-data

You should see the Matomo archiver line in the output:

5 * * * * /usr/bin/php /var/www/matomo/console core:archive --url=https://matomo.example.com/ >> /var/log/matomo-archive.log 2>&1

After the first scheduled run, inspect the log with sudo tail -20 /var/log/matomo-archive.log. This tail command guide is useful if you want to follow the log live while you tune report generation.

Tune Matomo reporting on Ubuntu

These changes are optional. Leave the defaults in place unless your traffic level or reporting needs give you a reason to change Matomo’s archive size and retention behavior.

Adjust Matomo report limits in config.ini.php

Large sites sometimes need higher row limits so Matomo keeps more detail in archived reports:

sudo nano /var/www/matomo/config/config.ini.php

Add or update these values under the [General] section:

[General]
datatable_archiving_maximum_rows_referrers = 5000
datatable_archiving_maximum_rows_subtable_referrers = 5000
datatable_archiving_maximum_rows_actions = 5000
datatable_archiving_maximum_rows_subtable_actions = 5000
datatable_archiving_maximum_rows_events = 5000
datatable_archiving_maximum_rows_subtable_events = 500
datatable_archiving_maximum_rows_site_search = 5000

Higher values preserve more detail but also grow the database and make the archiver work harder. Watch the archive log after changes and back the values down if one archive run starts overlapping the next.

For broader platform tuning, plugin references, and long-term maintenance, use the current Matomo guides and documentation.

Troubleshoot Matomo on Ubuntu

Fix duplicate try_files errors in the Matomo Nginx config on Ubuntu

If sudo nginx -t fails right after you paste the server block, Ubuntu’s bundled PHP snippet is the first place to look.

A duplicate try_files error looks like this:

2026/03/20 08:56:46 [emerg] 22556#22556: "try_files" directive is duplicate in /etc/nginx/sites-enabled/matomo.conf:14
nginx: configuration file /etc/nginx/nginx.conf test failed

That happens when the server block includes try_files $fastcgi_script_name =404; even though Ubuntu’s snippets/fastcgi-php.conf already provides its own try_files rule. Remove the duplicate line, then test Nginx again:

sudo sed -i '/try_files \$fastcgi_script_name =404;/d' /etc/nginx/sites-available/matomo.conf
sudo nginx -t

A corrected configuration returns the normal success output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Fix Matomo 502 errors on Ubuntu by matching the PHP-FPM socket

A 502 response usually means Nginx is pointing at the wrong PHP-FPM socket or the matching service is down.

Check which PHP sockets actually exist:

ls /run/php/

Ubuntu 26.04 shows this by default:

php-fpm.sock
php8.5-fpm.pid
php8.5-fpm.sock

If your server block still points at php8.3-fpm.sock or php8.1-fpm.sock on a 26.04 host, update fastcgi_pass, then restart the matching PHP-FPM service and Nginx:

sudo systemctl restart php8.5-fpm nginx
systemctl status php8.5-fpm --no-pager

A healthy PHP-FPM service returns:

● php8.5-fpm.service - The PHP 8.5 FastCGI Process Manager
     Loaded: loaded (/usr/lib/systemd/system/php8.5-fpm.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-03-20 08:55:17 AWST; 5min ago
 Invocation: ef90806f50cd4750825c16ee5c30e423
       Docs: man:php-fpm8.5(8)
   Main PID: 20818 (php-fpm8.5)

Fix Matomo database connection errors on Ubuntu

If the installer cannot connect to MariaDB, confirm the Matomo account still has the expected grant on the right database.

sudo mariadb -e "SHOW GRANTS FOR 'matomo_user'@'localhost';"

The result should include the database-specific privilege:

Grants for matomo_user@localhost
GRANT USAGE ON *.* TO `matomo_user`@`localhost` IDENTIFIED BY PASSWORD '*E8266F4F0C0EF64732AAFC4F13321F3BA61A5FF0'
GRANT ALL PRIVILEGES ON `matomo_db`.* TO `matomo_user`@`localhost`

If the final grant line is missing, reconnect to MariaDB and re-run the GRANT ALL PRIVILEGES ON matomo_db.* statement from the database-setup section.

Fix Matomo file permission errors on Ubuntu

If Matomo reports that tmp or config is not writable, restore the web-root ownership and standard file modes:

sudo chown -R www-data:www-data /var/www/matomo
sudo find /var/www/matomo -type d -exec chmod 755 {} \;
sudo find /var/www/matomo -type f -exec chmod 644 {} \;
sudo ls -ld /var/www/matomo/config /var/www/matomo/tmp

After the fix, the writable directories should still belong to www-data:

drwxr-xr-x 3 www-data www-data 4096 Mar 20 08:58 /var/www/matomo/config
drwxr-xr-x 8 www-data www-data 4096 Mar 20 08:58 /var/www/matomo/tmp

Remove Matomo from Ubuntu

This removal path deletes the Matomo application tree, the dedicated Nginx site, the Matomo database, and the scheduled archiver entry while leaving the rest of the LEMP stack available for other applications.

Remove Matomo files, Nginx config, and logs from Ubuntu

These commands permanently delete the Matomo application files, generated reports, and local log files. Export any analytics data you still need before you continue.

sudo rm -rf /var/www/matomo
sudo rm -f /etc/nginx/sites-enabled/matomo.conf
sudo rm -f /etc/nginx/sites-available/matomo.conf
sudo rm -f /var/log/nginx/matomo.access.log /var/log/nginx/matomo.error.log /var/log/matomo-archive.log
sudo nginx -t
sudo systemctl reload nginx

Verify the files are gone and Nginx still parses cleanly:

sudo test ! -d /var/www/matomo && echo "Matomo files removed"
sudo nginx -t

The verification should confirm both the missing directory and a valid Nginx config:

Matomo files removed
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Remove the Matomo database and user on Ubuntu

Drop the dedicated database and its login from MariaDB:

sudo mariadb

DROP DATABASE IF EXISTS matomo_db;
DROP USER IF EXISTS 'matomo_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Check that the database is gone:

sudo mariadb -Nse "SELECT 'Database removed' WHERE NOT EXISTS (SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME='matomo_db');"

A successful cleanup prints:

Database removed

Remove the Matomo archiver cron entry on Ubuntu

Edit the www-data crontab and remove only the line that runs /var/www/matomo/console core:archive. This keeps any unrelated web-application cron jobs intact.

sudo crontab -e -u www-data

After you save the edited crontab, confirm the Matomo line no longer exists:

sudo crontab -l -u www-data 2>/dev/null | grep -F '/var/www/matomo/console core:archive' || echo "Matomo archive cron job removed"

The confirmation message should be:

Matomo archive cron job removed

Remove the Matomo TLS certificate on Ubuntu

If you created a dedicated Let’s Encrypt certificate for Matomo, remove it with Certbot:

sudo certbot delete --cert-name matomo.example.com

Replace matomo.example.com with the real hostname you used when you requested the certificate.

Matomo on Ubuntu FAQ

Conclusion

Matomo is now running on Ubuntu with Nginx, MariaDB, PHP-FPM, and the official archive workflow, so you can collect analytics without handing raw visitor data to a third party. For the next round of web-server tuning, set up FastCGI cache on Ubuntu or configure security headers in Nginx.