Install Mautic Plugin for dummies & marketers too

How to Install Mautic Plugins

Installing Mautic plugins is really simple… most of the time…
But there’s always some obscure unofficial plugin that you really need so badly, and those always have little or no instructions and hence they refuse to install.

Don’t worry, it really is very simple, if you know a couple of tricks… Let’s start with the basics:

Always test new plugins in a test VPS or a separated Hosting account.

99% of Mautic plugins will be safe to just install, play around to see if you like it and delete it if you don’t, but Mautic is a complex piece of software built upon many other apps and frameworks, even the best of plugins, given an untested chain of events or given an untested stack WILL cause problems to a few percentage of users until (if ever) all the bugs and issues are solved, so always stay on the safe side, have a test server, which should replicate your production environment as closely as possible, where you can test any new plugins before you install them on your production environment.

Always backup your server before installing a new plugin, yes even if you tested it on another server.

Yes, everyone knows this, but also everyone skips this step now and then… you really don’t want to be that fool, I talk from experience ;P
And yes, backing up is boring and sometimes feels like losing valuable time, but if you automate your backups, then it becomes a simple and very satisfactory task, here’s a post I made about backing up Mautic

Installing an official Mautic plugin

All the official plugins come pre-installed by default, they are just hidden, so to install an official plugin, you just need to login to your Mautic installation, go to settings (click on the wheel, like on the first image)

A new menu will deploy (image 2) And the last item is precisely plugins.

If this is the first time you do this, you will see that just a couple of plugins are already available. But Mautic comes packed with several more plugins from scratch, to reveal them, just click the Install/Upgrade Plugins button and many more will appear.

Now you just need to select (click on) any plugin available in this screen and click the very same Install/Upgrade button once again and your new plugin will be installed.

In a future post, I will detail how to configure the most popular plugins, but that’s beyond today’s post. 

Installing a non-default plugin

For installing a non-default plugin, that would be any plugin that does not come pre-installed with Mautic, will require you to upload the plugin’s files manually to your server. For that, you will, of course, need the plugin files in the first place.

Where to find plugins

There are 2 main sources for Mautic plugins, the main one being GitHub. You can search GitHub for Mautic plugins or Mautic Mixins 😛 or you can use the second source and the most practical, because you can discover all the Mautic plugins in one place, which is Chris Calabro’s Mautic Plugins and Integrations (The Complete List), a well maintained and, as the name suggests, complete list of Mautic plugins.
Once you find a plugin that you are interested in, clicking the link will take you to the appropriated GitHub page, where you can download the plugin files.

The “easy to install” plugins

Let’s use as an example the Mautic reCAPTCHA plugin, if you go to the GitHub page for this plugin and scroll down you will find simple and complete instructions on how to install it, these same instructions are valid for most plugins, so I’m just going to copy them here below:

Installation via .zip

  1. Download the, extract it into the plugins/ directory and rename the new directory to MauticRecaptchaBundle.
  2. Clear the cache via console command php app/console cache:clear --env=prod (might take a while) OR manually delete the app/cache/prod directory.

So you just need to download the file, as they provided you with a link in the instructions text, you just need to click it and the file will download.
In case the link is not provided (very common), you just need to go up to the top of the same page and click the big green button that reads “Clone or Download”

Save the file in your hard drive, and now use WinZip, WinRAR or any other tool you like to uncompress the files, after that we will need to upload the files to your server, we can use FTP or SFTP for that, if you feel intrepid and have access to an SSH console you can also use this method.

Upload the Mautic plugin files to your server

Using your favorite tool, you can upload the files to your server, I will be using WinSCP cause I like my FTP transfers to be secure.
You will need to navigate to where your Mautic installation resides, if you are using Ubuntu like myself, this will be something like /var/www/mautic/html. If you are using shared web hosting (shame on you) it’s even simpler as you will probably have access only to your own directory.

Now find the plugins directory, there you will find a few directories, Copy here the unzipped directory containing the plugin files.

Properly naming the plugin’s folder

After uploading the folder, pay attention to how the naming of all the other directories, they follow a similar pattern, all except the one you just uploaded, in this case, the zip file is already named very similarly, but with added dashes and the last word forming the folder name is “master”, that won’t work! Mautic will not recognize the directory as a plugin if it doesn’t follow the proper naming convention (which is undocumented but pretty easy to replicate):

The pattern is Mautic+Whatevernamethepluginhas+Bundle, so whatever name the zipped file from GitHub has, you need to change it and rename the directory to follow this pattern or Mautic will not recognize the folder as a plugin container.
That’s it!, you just solved the mystery of why that freaking plugin would not install… now you can just follow the standard steps:

  • Clear the cache via console command php app/console cache:clear --env=prod (might take a while) OR manually delete the app/cache/prod directory.
  • GO to Mautic’s plugins screen and hit the “Install/Upgrade Plugins” Button.

The plugin should now show up on your screen.
With this method, you should be able to install 90% of the existing Mautic plugins out there. But there are some others that are more obscure…

You can now “clear your cache” as suggested in the plugin installation instructions, I wrote a post about how to install and run Mautic Cron Jobs, the very same instructions apply to commands, you just don’t need the timing part.

Plugins requiring you to install Composer

Some plugins will ask you to install composer and run some composer commands (that do not work without installing composer). Usually these plugins are highly geared towards developers, meaning they are still under development and were published on GitHub for sharing, discussing and improving the code among developers. I suggest you stay away from this type of plugins as the authors are not sharing it for general use, it’s that or they where too lazy to provide proper instructions for regular users to install the plugin, either way, if you are reading this is because you are not ready for dealing with the issues that will come ahead.
But if you are reading this you will try anyway, so here’s how to do it…

Installing without composer:

Composer is a very useful tool for developers with powerful commands that will save you a lot of time if you already know how to use it, but in the simple case of installing a Mautic plugin, what composer does is just downloading the plugin from GitHub and saving it in the proper folder with the proper name, which means you can follow the exact steps outlined in the previous sections of this post and just ignore the developer’s installation instructions. This process will allow you to install almost any other plugin out there.

Plugins needing 3rd party packages. 

Some plugins require some extra 3rd party software to work, the specific installation procedures will vary greatly depending on the 3rd party software to be installed, sometimes you just need to add one PHP file to your root directory, others will need extra steps.

Composer is among the most used apps for mautic installations, it’s not the 3rd party software itself, it’s a dependency manager specific for PHP, which is the language Mautic is built with, so you might find this one a lot in the future…

For example, the MauticFBAdsLeadAdsBundle plugin clearly specifies that you require an extra library: facebook/php-ads-sdk:2.9.* In that case, you will have to install that library. I am against installing any apps in the server that are not strictly required, however, composer will manage any dependencies automatically for you. You could, of course, do this manually, but sometimes there are a lot of dependencies and can be difficult to manage manually. If you have a test server, you could install composer on the test server only and then copy the resulting files composer worked out for you to your production server so you don’t need to install composer on your prod environment.

Installing Composer for it to manage your package installation is done via SSH console with one simple command:

sudo apt install composer

You can now install any library required by your plugin to work, in the case of this example it would be:

composer require facebook/php-ads-sdk:2.9.*

Keep in mind composer commands have to be executed on/from the folder where you want them applied to.
Here’s a basic introductory guide to composer.

Plugins without any instructions or with instructions that are not understandable.

JUST STAY AWAY! If the author didn’t care enough to write 4 lines of text with the most simple instructions, that’s exactly the same he will care if you need help later on.

Making it work is not the same as keeping it working

Many times, after finding a good looking piece of software on Github, I usually get excited about it, install it, learn how it works, solve a couple of easy to solve issues with the help of Google, but oftentimes this is not enough and then something comes up that I don’t know how to solve and I can’t find any solution with Google, then I open an issue on the GitHub page… wait one day, check back again in three days, then the following week… NO ANSWER.
Nowadays, whenever I find any new, good looking piece of software, I open 2 issues, one with a simple question and one with a feature request, and I wait to see what happens, if I get an answer, I bother installing, learning and fixing, otherwise, I just run away… Bottom line, not all that glitters is gold. One thing is making it work for the first time, a very different one is keeping it working under load, make use of your common sense, you’ve been warned!

Stay tuned for more Mautic goodies for Marketers… one per week or you get your money back ^m^

Yosu Cadilla

Hi, thank you for reading this article, hope you found it useful.

My name is Yosu Cadilla, I’ve been both a Marketer since 1996 and a Systems Administrator since 2000, switching back and forth and mixing both trades. Since discovering Mautic, I’ve been specializing in large Mautic deployments as well as Mautic for agencies. Nowadays all my clients are Mautic related.

If you are planning on deploying Mautic on a large scale, or if you are undecided about Mautic being a good fit for your organization… let’s have a chat!