Mautic upgrades from the command line and Composer: where to start
Teams running self-hosted Mautic can no longer update from the browser after Mautic 5.0, so every upgrade now runs at the command line. The first decision is which path applies: a package install updates with the mautic:update commands, while a Composer-based install changes Mautic package versions in composer.json and runs composer update before the same finishing step. Identify your install type before reading any upgrade steps, because the two paths share a goal but use different commands. Check how Mautic was installed, where the project files live and which system user owns them. If you are unsure, look for composer.json and composer.lock in the project root and confirm with whoever performed the original installation.
Mautic's stated release cadence has three layers: monthly patch releases, minor releases every three months and major releases every two years. Patches and minors are routine maintenance, and majors are planning events that need a dedicated test cycle. Your target should sit on a release line that still receives security fixes for the period you intend to run it. The Mautic releases page lists 5.2 (Capella) with security support until 30 June 2026, 6.0 (Tabit) with security support until 30 September 2026, and 7.2 (Absolunto) with active and security support until 30 September 2026. Confirm these dates on the day you plan, because a line that is supported now may be close to its end when your change window opens.
Mautic 7.3 is planned as the long-term support release, with security support through 31 December 2027. For teams that want fewer major upgrades, that makes it the line to evaluate first. Because it is a planned release, confirm its availability, release notes and timing with the Mautic project before you commit a schedule to it. A practical exercise is to write down the line you run today, the date each candidate line loses security support and the next supported line you would move to. That table shows whether you can reach 7.3 in one step or whether an intermediate upgrade is needed, and it gives your change calendar a fixed reference point.
Before choosing a target, check your platform against the stated requirements for Mautic 7.0. The project lists PHP 8.2, 8.3, 8.4 or 8.5, MySQL 5.7 or higher with InnoDB or MariaDB 10.2 or higher, and Apache, Nginx or IIS as the web server. From Mautic 5.0 onward, npm is also required. The project also states that Mautic should not be installed on shared hosting and recommends a VPS or dedicated server. Turn each item into a question for your platform owner: which PHP versions are installed on the web and build hosts, whether the database engine uses InnoDB, and whether npm is available where the front-end assets are built. Resolve any gap in a test environment before the production window.
Write down four things before anyone runs a command: your install type, your current release line, your target line and the platform gaps you found. Those four items determine the rest of the plan, including which command sequence applies, how much time the test cycle needs and whether a platform change must land first. Keep the record with your runbook so that the next patch or minor release starts from the same facts.
What changes between Mautic release lines and what it means for your upgrade
This table compares what changed across Mautic release lines from 4.0 through 7.2 and what each change asks of your upgrade plan. Read each row against your current version, your install method and your target release. The main takeaway is that the update path, PHP and database versions and support end dates must all be checked before you schedule the command-line update.
| Change | What it means for your upgrade | Action to take |
|---|---|---|
| Browser updates removed from 5.0 | From 5.0 onward, updates can no longer run in the browser and must run at the command line. | Run every upgrade from 5.0 onward as a command-line job under the web server user. |
| npm required from 5.0 | Mautic 5.0 and later need npm available on the server or build host where the update runs. | Confirm the npm and Node.js versions the target release expects, then check them in the test environment. |
| Composer recommended project template since 4.0 | Composer installs follow the recommended project template, and the update changes Mautic package versions in composer.json. | Confirm your install method first, then follow either the Composer or the non-Composer update path. |
| PHP 8.2 to 8.5 supported in 7.2 | Mautic 7.2 supports PHP 8.2 to 8.5, so your target PHP version must fall within that range. | Check the PHP version on your server and upgrade PHP in the test environment first if needed. |
| PHP and database requirements in 7.0 | Mautic 7.0 requires PHP 8.2 to 8.5, MySQL 5.7 or higher with InnoDB, or MariaDB 10.2 or higher. | Compare your PHP and database versions with these requirements before scheduling the update. |
| Security support end dates for 5.2, 6.0 and 7.2 | 5.2 ends 30 June 2026. 6.0 and 7.2 end 30 September 2026. 7.3 is planned for security support through 31 December 2027. | Confirm today's date against these dates and plan a move to a supported release line if needed. |
| Breaking changes and deprecations | Not listed here. Each target version may add changes that affect your install, configuration or extensions. | Read the release notes for the exact target version before the test upgrade. |
Which upgrade path fits your install type
The first decision is which of the two supported paths matches how your Mautic was installed, because each path changes different files and uses different commands. Check the install method before you touch anything. Look in the application root for a composer.json file and a composer.lock file, and find out whether your team or your deployment pipeline runs composer commands against this directory. If the site was installed from the production package with the web or command-line installer and has no Composer project files, it is a non-Composer install. If it was created from the Composer recommended project template, which the installation docs describe as the approach since version 4.0, treat it as a Composer install. Confirm this with the person who performed the original installation, because the files alone can be misleading after years of manual changes.
A non-Composer install uses three console commands, run from the application root as the web server user such as www-data so that files written during the update keep the ownership the web server expects. Run php bin/console mautic:update:find to see whether an update is available for your installation. Then run php bin/console mautic:update:apply to download and apply the package, and finish with php bin/console mautic:update:apply --finish to complete the post-update steps. Record the output of each command in your change ticket so the sequence can be reviewed or repeated. Keep the backup you verified in a test environment open alongside the runbook so you can restore quickly if a step fails.
A Composer install follows a different sequence. Back up composer.json and composer.lock first, because together they record the exact package set your site runs. Then change every Mautic package version in composer.json to the target release, and run composer update --with-dependencies so Mautic's dependencies resolve to versions that match the target. Finish with bin/console mautic:update:apply --finish. Before you edit any version constraint, confirm the PHP version range for the target release against the Mautic requirements page, since supported PHP versions change between release lines. Make sure the web server user has write access to the vendor tree that Composer will modify, and run Composer as that same user so ownership stays consistent.
Mixing the two paths causes trouble because each one assumes it owns the code tree. If a Composer install is updated with the console package commands, the code on disk can drift away from what composer.json and composer.lock describe, and a later composer install or composer update may reverse or conflict with the change. Running composer update on a tree that was patched by hand can also produce a lock file that no longer matches the running code. The reverse problem is just as serious: a site with Composer files that is updated through the console path leaves composer.json pointing at an older release. Before every update, record which path you use, store that decision with the verified backup, and check that composer.lock matches the deployed code.
Preparation: backups, inventory and a test environment before any update
A Mautic update changes code, database schema and the way cron, queues and integrations behave, so the work starts before the update command. Each card below is a prerequisite you should confirm in writing, in your own environment, before a production upgrade begins.
Tested backup of files and database
Take a backup of both the application files and the database, then restore them into a separate test environment and confirm Mautic loads and the data is intact. The update guide requires this tested restore before any update, because an untested backup is not a recovery plan. Record who ran the restore, when, and which checks passed so the rollback path is known before production is touched.
Inventory of custom plugins and themes
List every custom plugin and theme on the instance, with its source, version and the Mautic release it was built against. Custom code is the most common reason an update stalls, so confirm each one loads and works on the target release in the test environment. Note any plugin that has been patched by hand, since those edits can be overwritten or conflict with the update.
Inventory of cron jobs and staggered schedules
Document each scheduled job: segment updates, campaign updates, campaign triggers and the broadcasts command for segment emails. The Mautic docs say these jobs should be staggered, so record the current timing and confirm it still works after the update. Check that each job runs as the web server user and that its logs show successful completions before and after the change.
Messenger consumer and queued email
If email is queued, identify the messenger consumer process, how it is started and what supervises it. Confirm whether it must be restarted after an update so it picks up new code, and check that the queue is drained or understood before you begin. A consumer left running on old code can process messages incorrectly, so plan its stop and restart as an explicit step.
Integrations and SAML single sign-on
List every integration, including CRM connectors such as HubSpot or Salesforce and any SAML single sign-on configuration. For each one, record its credentials, field mappings and sync direction, and confirm it still works against the test copy. SAML depends on the identity provider sending email, first name and last name attributes, so verify those claims before and after the update.
PHP, database and hosting confirmation
Confirm the PHP and database versions the target release requires, using the Mautic requirements page as the reference, and check them on both production and the test environment. Mautic should run on a VPS or dedicated server rather than shared hosting, so verify your host meets that standard and has the file permissions the web server user needs. Ask your platform owner to confirm these details in writing before scheduling the update.
Running the upgrade sequence with checks and rollback points
The sequence runs the same stages on both install paths: confirm the tested backup, open a maintenance window, update the files, complete the database step, then check the systems around Mautic. Each stage closes with a check and a rollback point, so a failed stage can be restored from the tested backup before the next one starts. Ask your internal team or partner to confirm each command against the release notes for your target version.
Confirm the tested backup before any change
Before the first command, confirm that the backup of files and database was restored and checked in a test environment, as Mautic's update guide requires. Record where the backup is stored, who can restore it, and which version it came from. Mark this point as rollback point one. The step is done when someone other than the operator has restored the backup in the test environment and confirmed that the site loads and the database opens.
Open a maintenance window and pause activity
Put the site into maintenance using the page or web server setting your team uses, so visitors and contacts do not interact with it during the update. Stop new campaign sends and contact imports, then pause the cron jobs for segment updates, campaign updates, campaign triggers and the broadcasts command. If emails are queued, check the cron documentation for your version on how to pause the messenger consumer, and record the queue state. The step is done when no Mautic jobs are running and the queue state is written down.
Run the file stage as the web server user
Run every Mautic command as the web server user such as www-data so new files keep the ownership the web server expects. On a package install, run php bin/console mautic:update:find, then php bin/console mautic:update:apply. On a Composer install, back up composer.json and composer.lock, change all Mautic package versions to the target, then run composer update --with-dependencies. After this stage, check the ownership of the Mautic directory and fix any file left owned by root before continuing. Mark rollback point two here.
Complete the database step with --finish
Run php bin/console mautic:update:apply --finish as the web server user to complete the update, including the database changes the target release requires. Keep the full command output in the change record and watch for errors. Afterward, confirm that the version shown in the admin area matches the target and that the application logs show no new errors. Ownership should be checked again at this point. Mark rollback point three here. If the command fails, stop and move to the restore step.
Check cron jobs, queued email and integrations
Turn the cron jobs back on one at a time and keep them staggered, as the cron documentation advises. Watch that segment updates, campaign updates, triggers and the broadcasts command complete without errors. Confirm the messenger consumer is running if emails are queued, then send a test message to an internal address. Finally, check each integration, such as the HubSpot or Salesforce plugin, with a test contact action and confirm the record arrives. The step is done when the test send, the test sync and one full cron cycle complete without errors.
Restore from the tested backup if a stage fails
If a check fails at any rollback point, stop the sequence and restore from the tested backup confirmed in the first step. Restoring means putting back the files and the database together so they match the same point in time, then restoring the original file ownership. Confirm the version shown matches the pre-update version and keep the failed output with the change record so the cause can be fixed before a new attempt. The step is done when the site runs on the prior version and the cron, queue and integration checks pass again.
How to test an upgraded Mautic and roll back when it fails
Treat the test of an upgraded Mautic as a checklist that covers every path a marketing team depends on, and treat rollback as a rehearsed restore of the backup you tested before the update, not as an improvised reaction after production breaks. Mautic's update guide requires a tested backup of files and database, restored and checked in a test environment, before any update runs. The verification and rollback plan should be written before the maintenance window opens, with named owners for each check and a stated point at which the team chooses to roll back instead of fixing forward.
Start with access and data. Confirm that administrators and a sample of each user role can sign in, that role permissions still match the access model you documented, and that contact imports run end to end on a test file with known fields. Then confirm that segment updates and campaign updates run on schedule. Mautic relies on cron jobs for segment updates, campaign updates and campaign triggers, and those jobs should be staggered as the cron documentation describes. Check the job logs after the first scheduled runs, not only the command output from the update itself.
Next, test email delivery. Send a broadcast to a small internal segment and confirm that the broadcasts command picks it up and that queued messages are processed by the messenger consumer. A message that sits in the queue after the update usually means the consumer was not restarted or is running under a different user or configuration. Confirm that the CRM sync to HubSpot or Salesforce still pushes contacts through the plugin you use, and that field mappings and credentials work against a test record. If SAML single sign-on is enabled, test a full login through your identity provider, including the email, first name and last name attributes Mautic expects.
Test tracking and consent behavior last, because it is the easiest to break silently. Confirm that tracked page views and form submissions still attribute to the correct contact, that contacts who withdrew consent or opted out do not receive marketing email, and that the preference and consent settings you rely on for GDPR obligations still take effect. Record the results of each check with the version tested, the date, the tester and any defect, since that record is the evidence your change process will need. Confirm exact version requirements, including PHP and database versions, against the requirements page for your target release.
Plan rollback as restoring the tested backup of both files and database, with the restore rehearsed in a non-production environment before the production window. The rehearsal should measure how long the restore takes, confirm that the web server user can read and write the restored files, and confirm that the restored application starts and passes a short version of the checklist. Keep the composer.json and composer.lock copies with the file backup for Composer installs. Agree in advance who decides to roll back, the time limit for that decision and who communicates with marketing stakeholders. Ask your partner or internal team to confirm how long the restore takes in your own environment, because no general figure applies to every installation.
What makes a Mautic upgrade take longer
This table lists the factors that lengthen a command-line or Composer upgrade of self-hosted Mautic, with the direction each one pushes effort and what to ask a partner to price. Use it to check which drivers apply to your installation before you request a fixed-scope quote, since the same target version can be simple on one instance and slow on another.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Custom plugins and themes | More custom code means more compatibility checks against the target Symfony and Mautic APIs and more retesting of forms, pages and emails. | An inventory of each plugin and theme, its owner, and whether it is maintained upstream or in-house. |
| Composer dependency conflicts | Pinned or overridden packages can block composer update --with-dependencies, so resolving them often takes more time than the update command itself. | A dependency review of composer.json and composer.lock, with the conflicts found and how each will be resolved. |
| Number of integrations | Each CRM, SMS or email transport plugin adds a connection to test, credentials to rotate and sometimes a plugin version to match the new release. | A list of integrations with their plugin versions, the test cases for each and who validates them. |
| Database size | Larger tables extend the migration step and backup and restore testing, and they raise the risk of a long maintenance window. | Database size and row counts for contacts, events and campaign logs, and the restore test plan that uses them. |
| Queued email volume | Emails waiting in the queue must be drained or accounted for, and the messenger consumer must be stopped and restarted cleanly around the update. | Queue depth at the planned window, the drain approach, and how in-flight sends are verified afterwards. |
| Cron complexity | Staggered cron jobs for segments, campaigns and broadcasts must be paused, checked and resumed in order, and each job added to the schedule adds a verification step. | A list of every scheduled Mautic command, the host it runs on, and the steps to pause and resume them. |
| Number of instances | Each production, staging and secondary instance needs its own backup, update run, file permission check and smoke test. | The instance inventory, whether staging mirrors production, and whether the same runbook covers every instance. |
| Major versions crossed | Jumping several major releases multiplies PHP, database and dependency changes, and each major step may need its own test cycle. | The current and target versions, the PHP and database versions required by each step, and the support dates that apply to the target. |
What a Mautic upgrade quote should cover
A credible Mautic upgrade quote itemizes the work by stage, because the update commands are usually the shortest part of the job. The first line item is scoping the inventory: the installed release, PHP version, database engine and version, web server, whether the install is a package install or a Composer project, every installed plugin, the cron jobs for segment updates, campaign updates and triggers, the broadcasts command, and the messenger consumer if email is queued. The quote should also name each external integration, such as HubSpot or Salesforce, and whether SAML single sign-on is in use. Ask the provider to list what it will check and what it will leave for you to confirm.
The second and third line items are the test environment and the backup restore. The Mautic update guide requires a tested backup, meaning files and database restored and checked in a test environment before any update runs. A quote should state who builds that environment, which PHP and database versions it matches, and how the restored copy is validated, including logins, cron behavior and outbound email. Infrastructure costs for the test environment are usually billed separately from labor, so ask whether they are included or whether you will provision them yourself.
The update path is the fourth line item. For package installs, the quote should cover running the find, apply and finish steps with php bin/console as the web server user, such as www-data, so file permissions stay correct. For Composer installs, it should cover backing up composer.json and composer.lock, changing the Mautic package versions to the target, running composer update with dependencies and finishing with mautic:update:apply --finish. Ask whether the quote includes intermediate releases if the target is several steps ahead, and whether a rerun is included if a step fails.
The fifth and sixth line items are integration testing and rollback rehearsal. Integration testing should confirm that contact sync, plugin behavior and SSO still work on the upgraded release. Rollback rehearsal means restoring the pre-upgrade backup into the test environment and proving the steps work before production is touched. Both are easy to omit and expensive to discover during an incident. Also confirm how the quote handles findings that point to custom code or unsupported plugins, since those may need a separate scope.
One-time upgrade work is separate from recurring retainer support. The upgrade is a fixed-scope engagement, and a fixed-scope quote follows a written scope that lists deliverables and timelines before work starts. Ongoing monthly and quarterly patching, release monitoring and support are offered as retainers. Plan the timing with the Mautic releases page: 5.2 receives security support until 30 June 2026, 6.0 and 7.2 until 30 September 2026, and 4.4 has paid Extended Long Term Support through 31 December 2026. DeployOpen does not publish prices, so ask for a quote built from the written scope.
Mautic upgrade questions buyers ask before hiring help
Can our team upgrade Mautic ourselves without a partner?
Yes, if your team has Linux administration skills, server access and time to run a full rehearsal. Package installs update from the command line with php bin/console mautic:update:find, mautic:update:apply and mautic:update:apply --finish, each run as the web server user such as www-data so file permissions stay correct. Composer installs follow a separate sequence. Internal teams usually stall on the surrounding work: building a test environment that matches production, proving the backup restores, and getting marketing operations to check campaigns, segments, cron-driven jobs and email sending after the change. Confirm that someone owns each of those before you decide.
What drives the cost of a Mautic upgrade?
Cost follows how much verification the instance needs and how many moving parts it has. The main drivers are the version gap to the target, any custom plugins or themes, integrations such as HubSpot or Salesforce that need re-testing, database size, how many cron jobs and queued email consumers must be checked, and how many stakeholders must sign off. One-time work covers assessment, the test environment, rehearsal, the production run and fixes found in testing. Recurring costs appear only if you keep someone on patches and future releases. Ask for a quote that lists each of these as its own line, so you can see what you would take in-house.
How long does a Mautic upgrade take?
Duration depends on the same drivers as cost, so ask for milestones instead of one number: assessment, test environment, rehearsal, production window and sign-off. The version gap matters because Mautic publishes monthly patch releases, minor releases every three months and major releases every two years, so an instance that has fallen several releases behind carries more change to test. Custom code and integrations extend testing, and the time your staff can give to sign-off often sets the calendar more than the commands do. Ask the provider to state which of these assumptions appear in the written scope, and which ones they expect you to supply.
What does a Mautic upgrade need from our team?
Plan for access, an environment and people. You will need shell access to the server, the web root, database credentials, administrator access inside Mautic, and a non-production copy to rehearse on. Before any update, a tested backup must exist: files and database restored and checked in a test environment. You also need a maintenance window, the ability to pause and verify cron jobs, broadcasts and the messenger consumer, and named staff who approve results from both marketing and technical sides. Ask who holds each item, and confirm that your hosting setup allows the commands you will run.
Does a Composer-based Mautic install need a different upgrade path?
Yes. Composer installs use a different sequence. Back up composer.json and composer.lock, change every Mautic package version to the target release, run composer update --with-dependencies, then finish with bin/console mautic:update:apply --finish. The package-install commands do not replace these steps. Check whether your install came from the Composer project template, which the project has recommended since version 4.0, before you plan. Run the commands as the web server user so Composer does not leave files owned by the wrong account. Test dependency changes in a copy first, because dependency updates can change more than Mautic itself.
Why is the browser update gone from Mautic?
Mautic removed the ability to update in the browser from version 5.0, so every upgrade now runs at the command line. The project's update documentation sets that method, and any runbook written for the browser flow is out of date. For planning, someone with shell access must be present, and your change record should name the commands and the user that runs them. The reason for the change is worth confirming in the project's update documentation before you write your procedure. If your team has only used the admin interface for updates, budget time for training on the command-line steps and for a dry run.
What happens to Mautic 7.2 after 7.3 becomes long-term support?
Mautic 7.2 (Absolunto) receives active and security support until 30 September 2026. Mautic 7.3 is planned as the long-term support release, with security support through 31 December 2027. Plan to move from 7.2 to 7.3 once 7.3 is released and your testing has passed, and confirm the release date and status on the Mautic releases page. Older lines have shorter windows: 6.0 has security support until 30 September 2026, 5.2 until 30 June 2026, and 4.4 has paid Extended Long Term Support through 31 December 2026. If you run an older line, ask what the paid extension covers and what it costs. Ask any provider to write the target version and its support dates into the scope.
How DeployOpen works on this
DeployOpen plans and carries out Mautic upgrades inside your own infrastructure, starting from a tested backup and running the update commands for your install method. Each engagement follows a written scope, so the install type, target release and test steps are agreed before any production change.
How we scope
- Confirm whether the install is package-based or Composer-based, since the update path differs for each.
- Agree the target Mautic release line and the PHP and database versions it requires in your environment.
- Define the written scope, including backup and restore testing, cron and queue checks, and the rollback plan.
How we build
- Restore a full backup of files and database into a test environment and confirm the copy works before any update.
- Run mautic:update:find and mautic:update:apply with --finish as the web server user, or change package versions in composer.json and run composer update --with-dependencies.
- Test logins, campaigns, segment updates, broadcasts and queued email in staging before the production change.
How we hand over
- Deliver a written runbook covering the exact commands, the user account used and the order of steps.
- Document the backup, restore and rollback procedure with the evidence gathered from the test restore.
- Walk your team through the post-upgrade checks so they can repeat the process at the next release.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the handover.
- Retainers can cover planning for each monthly, quarterly or two-yearly release on your chosen schedule.
- Confirm with DeployOpen the support terms for your release line before the engagement starts.
