Skip to content

Adds matomo plugin directory env documentation #836

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bomoko wants to merge 2 commits into
base: live
Choose a base branch
from
Open

Adds matomo plugin directory env documentation #836

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d85f439
Adds matomo plugin directory env documentation
Aug 25, 2025
91941a0
Update how-piwik-works.md
bomoko Sep 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/5.x/how-piwik-works.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,27 @@ Matomo Core only defines the main processes and behaviours. Plugins can extend a

You can read more about this topic in the ["Matomo's Extensibility Points" guide](/guides/piwiks-extensibility-points).

## Fine grained plugin directory and download control

Matomo allows for a fair amount of control over where plugins are downloaded, installed, and discovered, beyond the standard `./plugins` directory. This is particularly handy in non-standard deployment configurations, such as when Matomo is deployed in containerized or read-only deployments where the core code is immutable, but you want to allow users the ability to download and install additional plugins.

This is achieved through the use of the environment variables `MATOMO_PLUGIN_DIRS` and `MATOMO_PLUGIN_COPY_DIR`.

### MATOMO_PLUGIN_DIRS

Setting this environment variable allows you to register additional plugin locations beyond the default. It describes the plugin locations through a colon-separated list of entries, where each entry has the form `ABSOLUTE_PATH;RELATIVE_WEBROOT_PATH`. The _absolute path_ is where the plugin code lives on disk; the relative path is how that same location is exposed under the Matomo webroot (so plugin assets resolve correctly). Both parts are required, and Matomo normalizes trailing slashes.

*Example:*
`MATOMO_PLUGIN_DIRS="/var/www/html/plugins;plugins:/srv/matomo-plugins;matomo-plugins"`

You can declare this via environment variables, or alternatively by setting $GLOBALS['MATOMO_PLUGIN_DIRS'] in bootstrap.php.

### MATOMO_PLUGIN_COPY_DIR

To control where Marketplace or ZIP installs are written, set `MATOMO_PLUGIN_COPY_DIR` to one of the absolute paths already listed in MATOMO_PLUGIN_DIRS.

**Warning:** The directory must be writable by the web server user, otherwise plugin installation will fail. If the specified path is invalid or not writable, Matomo will either display an error message or fallback to installing plugins in the core `./plugins` directory, depending on the situation.


## Other valuable resources

Expand Down