How To Update MODX Advanced Installs

Jan 6, 2012

Read this if all of the following apply to you:

  1. You are running a site on MODX, the most advanced CMS in the world.
  2. You want to update/upgrade MODX to the most recent version.
  3. You want a smooth update with minimal downtime.
  4. You are NOT upgrading to a new branch, meaning you're going from 2.1.x to 2.1.x or 2.2.x to 2.2.x, etc. If you are jumping branches, this tutorial will probably still work but you might need to do some housecleaning.
  5. You are using the Advanced Installation. If you want to know more about the Advanced Installation option, comment below and I'll write a new post about it. ****UPDATE:** read it here.

Ok here goes, step-by-step:

  1. BACKUP YOUR SITE!!! Login to cPanel or whatever hosting account administration area you use, and download a full backup of your site. That means your "home directory" AND your MySQL database. Make sure you read my disclaimer - and don't mess up your site by not backing up!!
  2. Using the File Manager module in cPanel, navigate to your root directory » /home/username/. Select the /public_html folder and compress an archive of it into the root directory. Also do this for the /core folder. If the /core folder is not in /home/username/, you are probably not using the Advanced Installation. This step is extra backup with easy access on your server (so you don't have to upload a full backup to restore your site). Skip it at your own discretion.
  3. Download the .zip file for the MODX version you want to install, then upload it to /home/username/. You can also use SSH and wget to do this ten times faster.
  4. Extract the contents of the MODX .zip file into /home/username/. You should now have a new folder with the same name as the .zip file » /home/username/modx-etc-etc/. Inside you should find 2 folders: /core and /setup.
  5. Important!! - go back to the root directory and RENAME the existing /core folder there. I use "coreOLD" - anything that signifies the old version. You want to rename it and NOT delete it yet because you'll be using some of the files there. At this point your site will be inaccessible.
  6. Copy the new /core folder from /home/username/modx-etc-etc/core to /home/username/core. So at this point you've renamed the OLD core and put the NEW core in its place.
  7. Copy /home/username/coreOLD/components to /home/username/core/components. This is to ensure your installed addons will work with the new MODX.
  8. Navigate to the /home/username/coreOLD/packages and copy all the files and folders in there EXCEPT the folder "core" and the file "" over to home/username/core/packages/. Be extra careful not to copy over, or you'll be installing the old version again ;) You've just copied all your transport packages to the new core so MODX Package Manager knows where to find them.
  9. Copy the contents of /home/username/coreOLD/config/ to /home/username/core/config/. You've copied your MODX config files so the Installer script knows it's an upgrade and not a new installation.
  10. Copy the /home/username/modx-etc-etc/setup folder to /public_html/setup.
  11. Go to and run the Installer. When asked for a configuration key, make sure you enter the correct config key for your site. It's the name of your config file minus the extensions. For example if the filename is: /home/username/core/ your config key is: "customConfig" (without the quotes).
  12. The next Installer screen should have "Upgrade" selected as the installation option, the "Core is manually unpacked" should be UNchecked, because you have a fresh, new in there waiting to be installed. Run the installer. Voila!

At this point, you should be able to login to MODX and everything should be running exactly as before the update, without mucking around with Package Manager, or anything else. There's many, many ways to do an update, but I've repeatedly found this to be the most reliable.

Note: at Step 5, instead of renaming the old core folder and doing all that copying and pasting, you could just move the new core folder into place in the home directory and overwrite the old core. However, I've found this to be a bit less reliable. The other way, although slightly longer, gives you a fresh core with no orphaned files, etc. And if you know your way around cPanel File Manager at all, the whole process only takes 15 minutes or so.

Happy MODXing!!