How do I make Matomo for WordPress work when I have a custom content directory?

If you have configured a custom content directory using WP_CONTENT_DIR or are using symlinks, then parts of the plugin likely won’t work (eg the Matomo Reporting/Admin/Tag Manager pages) and you get a warning in the system report or an error pointing to this FAQ when you try to open for example the Matomo reporting page.

There are two ways to configure the path to the WordPress root directory that contains the file wp-load.php.

1. Through an environment variable

You can specify an environment variable (eg through apache or nginx) named MATOMO_WP_ROOT_PATH which points to the root directory of your WordPress directory. It needs to be an environment variable, defining a constant with the name MATOMO_WP_ROOT_PATH won’t work. If you set the environment variable through a web server, then only web requests will be fixed but not requests that are executed on the command line. That’s why we recommend you also add the following line to your wp-config.php which may fix report generation issues (archiving):

define('MATOMO_SUPPORT_ASYNC_ARCHIVING', false);

2. By creating a file in the plugins directory

Alternatively, you can place a file named matomo.wpload_dir.php in the WordPress plugins directory (eg wp-content/plugins/matomo.wpload_dir.php).
This file should include the path to your wp-load.php and can look like this:

<?php exit;
/var/www/html/wordpress

To avoid a PHP error should this file be opened directly you can place a comment before the directory path

<?php exit;
#/var/www/html/wordpress

Make sure the configured path is an absolute path that starts with a slash or backslash (depending on the operating system).