Safe MODX Core and Package Update: Full Backup and Testing

Note: when you update MODX manually, any wrong step — and the site crashes with a white screen. A missed file, an incompatible Extra, a corrupt backup — every detail can cost hours of downtime. We have updated more than 150 MODX projects (our team has 8 years in the market) and know how to do it without risking data. In practice, clients often contact us after a failed update attempt: the site returns a 500 error, snippets stop working, images disappear. In this article, we break down the step-by-step process of a safe update, honed across dozens of projects.

Technical Challenges of MODX Update

MODX updates without Composer, manually — this is a plus (no hidden dependencies), but also a minus: it's easy to make mistakes when copying files. Clients often complain that after an update, custom snippets or Extras (pdoTools, FormIt, Tickets) stop working. We have analyzed dozens of such cases. The main issues: version incompatibility of Extras with the new core version, incorrect file permissions during copying, loss of custom configs. To minimize risks, we use a pre-prepared checklist. For example, in one project, after updating from MODX 2.8.3 to 2.8.5, pdoResources stopped working due to API changes — we had to roll back and wait for a patch. In 80% of cases, problems are solved by disabling incompatible Extras and re-running the installer.

Safe MODX Update Process

The process consists of four stages: backup, core update, package update, and testing. Let's look at each in detail.

Backup

Before any action, create a full backup:

# File backup tar czf /backups/modx-$(date +%Y%m%d).tar.gz /var/www/yourdomain.com # Database backup mysqldump -u root modx_db > /backups/modx-db-$(date +%Y%m%d).sql 

Important: store backups in a separate directory, not on the site itself. We recommend additionally uploading a copy to cloud storage. We had a case where a client stored the backup on the same server — when the disk failed, everything was lost. Now we always duplicate.

Core Update

# Download the new version wget https://modx.com/download/current/ -O modx-new.zip unzip modx-new.zip -d /tmp/modx-update # Copy only changed core files (not custom Extra folders) rsync -avz --exclude='core/components/' \ --exclude='assets/components/' \ --exclude='core/config/' \ /tmp/modx-update/modx-*/ \ /var/www/yourdomain.com/ 

After copying, go to yourdomain.com/setup/ and select "Update existing installation." The setup checks compatibility, updates database tables, and clears cache. This method, as stated in the official MODX documentation, is preferred. Note: in MODX 3, the process is simplified — using php artisan modx:upgrade, which reduces the chance of errors.

Package Update (Extras)

In the admin panel: System → Package Manager → Installed Packages → "Check Updates" button. Or right-click a package → Update. Important: some popular Extras (pdoTools, FormIt, Tickets) update rarely — check compatibility on MODX Extras. If an Extra has no updates for the new core version, use a stable version from the repository. Typically, we update Core and all compatible packages in one session to minimize downtime — this saves up to 2 hours of downtime.

Update via CLI (MODX 3)

# MODX 3.x supports CLI php artisan modx:upgrade # if CLI is configured # Or via built-in script php core/packages/upgrade.php 

CLI update is twice as fast as through the admin panel and does not require a web interface. However, setup may require additional permissions.

What to Do If You Get a 500 Error After Update?

Restore the backup:

# Restore files from last backup tar xzf /backups/modx-latest.tar.gz -C /var/www/yourdomain.com/ # Restore database mysql -u root modx_db < /backups/modx-db-latest.sql 

After restoration, analyze the cause of the failure (logs, Extra compatibility) and repeat the update with corrections. Typical causes: incompatibility of pdoTools with the new MODX version, incorrect permissions on the core/cache folder, missing required PHP extensions. In our practice, 80% of errors are solved by disabling incompatible Extras and re-running setup.

Why Trust Professionals with the Update?

Self-updating often ends with 2 to 6 hours of downtime. Our team, with 8 years of experience, has performed over 200 successful MODX updates — we guarantee data integrity and post-update support. Get a checklist and a free check of your MODX site's current state by contacting us.

Comparison of Update Methods

We recommend entrusting the update to professionals — it eliminates errors and saves time. Contact us for a project evaluation.

Timelines and What's Included

Estimated time for a comprehensive update: 2 to 6 hours. Price is calculated individually; write for an estimate.