This guide will tell you how to upgrade your Mautic 3+ installation to Mautic 4+. I have to say to smoothest upgrade ever. All command included and some heads up.

Mautic 4 is the most stable release I’ve seen in years, we are already using it by many customers at Friendly. At the beginning of this year, when we upgraded from Mautic 2 to Mautic 3, we had several issues with the database structure and even the file system. This time the upgrade ran really well. Here is a simple guide how we did it.

In this tutorial I will use sudo commands just to make sure you can run all commands, even if you don’t log in as a user, that is in the www-data group. I know this is not the proper way, but it will work for those who don’t want to lose themselves in the mysteries of user privileges of Linux.

My Mautic install lives in /var/www/html/mautic and I will use all commands respectively. The previous install was running in a php7.3 environment, we will need to upgrade that to php7.4 as well.

Click here for a quick video to see why Mautic 4 is so awesome!

Let’s begin:

Backup everything

We are using Linux Containers, so we can create snapshots with just one click and revert if the sh1t hits the fan. But if you don’t you should make backups:

Backup file system

Navigate out from the Mautic folder to /var/www/html

zip -r folder1

Backup your database

mysqldump -u [user name] –p [password] [mautic database_name] > [dumpfilename.sql]

You can check if the files are created by running:

ls -la

You should see a .sql and a .zip files in there.

Environmental update

Update your php7.3 to php7.4 if you haven’t done yet:

apt install mariadb-server apache2 libapache2-mod-php7.4 php7.4 unzip php7.4-xml php7.4-mysql php7.4-imap php7.4-zip php7.4-intl php7.4-curl php7.4-gd php7.4-mbstring php7.4-bcmath ntp -y

Let’s change all environmental variables:

sudo nano /etc/php/7.4/apache2/php.ini

You’ll need to change the followings:

file_uploads = On
allow_url_fopen = On
short_open_tag = On
memory_limit = 256M
upload_max_filesize = 100M
max_execution_time = 300
post_max_size = 64M

Regarding memory limit, you can be more generous and lift to 512M as well. Upload max filessize is also up to you. I suggest a minimum of 20MB.

Now move to php4 officially, and restart our Apache.

sudo a2enmod php7.4
sudo a2dismod php7.3
sudo systemctl restart apache2

Let’s check the version:

php -v

You supposed to see something like this:

PHP 7.4.23 (cli) (built: Aug 26 2021 15:51:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.23, Copyright (c), by Zend Technologies

Get ready for the heart surgery. In order to do that we stop the heart: sStop the cronjobs from running.

sudo crontab -e

You can just add a # in front of the cron commands, like:

# * * * * * CRONJOBS HERE

Command line update

In order to create more tension we will do this in 2 steps. First we update to 3.3.4 and then to 4.0.1.

Let’s look for a new version:

cd /var/www/html/mautic
sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:find

The new version is found, let’s apply the update:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply

Now we are prompted to apply –finish. I would like to stop here for a moment. I know, that it is not the right way to use sudo when you are working here, but it is just simpler for folks if we don’t go into permissions. But using a root user during updates can cause file creation with the wrong ownership. In order to avoid it we will make sure by almost every step that the files belong to the right user. So we hand over the files to the www-data user all the time (which is running our we server.)

We do it by running this:

sudo chown -R www-data:www-data /var/www/html/mautic/
sudo chmod -R 755 /var/www/html/mautic/

And now we can finish:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply --finish

If everything went well, we are on the 3.3.4 version, half way to 4.0.1. Let’s look for a new version, and apply changes:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:find
sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply

Make sure file ownership is okay:

sudo chown -R www-data:www-data /var/www/html/mautic/
sudo chmod -R 755 /var/www/html/mautic/

And now hit a home run (A golden goal if you are in Europe.)

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply --finish

Congratulations! You are now officially on Mautic 4.0.1.


You need to make sure your templates are okay. Make sure, that all of your email / landing page templates have the following config file format especially the red line:

  "name": "Template name",
  "author": "Mautic team",
  "authorUrl": "",
  "builder": ["grapesjsbuilder"],
  "features": [

If you are upgrading from a previous version, all your templates will have “builder”: “grapesjsbuilder”, format, and you really need those brackets now.

Get Mautic Tips and Secrets in Your inbox!

In this weekly email you'll recieve never published guides, ready to deploy code samples, premium templates!

Troubleshooting help in the forums

You can find more help in the Mautic forums. Here are some of the issues I also ran into:

9 Comment

  • Daniel Wood


    and don’t forget to reenable Cronjobs and thanks for the next great guide!
    The main reason I used your last one is I couldn’t make this work on my Mautic 3 installation when I tried to do it myself unaided. I am just starting to try to use Mautic so luckily it wasn’t in production yet anyway.
    If only you had done this one first. Thanks again.

  • jos0405


    Hey, thx for the comment. Yeah Mautic install should be done with a checklist on your side to make sure nothing is left out.

    • Daniel Wood


      Thanks and sorry I am just coming back to this now. What I mean is your guide starts with disabling cronjobs but doesn’t re-enable them after, or am I missing something? Cheers.

  • Hermann


    Hey Joey,

    Thanks for this writeup, it helped me update to version 4 of Mautic, which is a godsend in what relates to the editor.

    I only had to warm the cache at the end for it to perfectly work.

    Once again, thanks!


  • Marcel


    Do I understand correctly that if you add the brackets for grapesjsbuilder, the v3 emails will work in v4?
    And this is made in the config.json file, correct?

  • Not so techy


    i tried to do this update but get this error in the log (and cant access contact view now)

    [2022-08-15 14:50:24] mautic.NOTICE: Doctrine\DBAL\Exception\SyntaxErrorException: An exception occurred while executing ‘ALTER TABLE m3_lead_event_log RENAME INDEX IDX_SEARCH TO m3_IDX_SEARCH’: SQLSTATE[42000]: Syntax error or access violation: 1064 You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near ‘INDEX IDX_SEARCH TO m3_IDX_SEARCH’ at line 1 (uncaught exception) at /home/ line 98 while running console command doctrine:migrations:migrate {“hostname”:“”,“pid”:19074}

    this is the same problem i had when updating from the app on the web

    any idea how to fix this?


Leave a Reply

Your email address will not be published. Required fields are marked *