Upgrading concrete5 8 to Concrete CMS 9

Concrete CMS 9 · Updated 2026-09-04

Version 8 of concrete5 is end of life: no security patches, an aging PHP ceiling, and a marketplace that no longer lists v8 add-ons. If you run an 8.x site you care about, the upgrade to 9 is overdue. It is not a one-click affair, mostly because of what sits around the core: your theme, your add-ons, and your PHP version. This guide is the order of operations that avoids the common failures: audit first, then latest 8.5, then PHP, then latest 9, then the theme. One change at a time, on a copy.

Before you start

The backup plan, the theme, and the add-ons decide how the upgrade goes, and all of them are cheaper to deal with before you touch the core.

There is no downgrade. Concrete's official documentation is blunt about this: the only way back is your backup. Take a database dump and a full file backup before every step below, and do the whole run on a staging copy first.

Your theme is the biggest job. Concrete 9's interface is built on Bootstrap 5; version 8 themes were built against Bootstrap 3. The site will run, but a legacy theme typically needs real rework, and if it was not namespaced under .ccm-page, its styles will fight the v9 editing interface. Budget more time for the theme than for the upgrade itself, and consider whether switching to a maintained 9.x theme is cheaper than porting.

Check every add-on now. The marketplace was relaunched in 2024 and v8-era add-ons were not carried over. For each installed package, find out whether a 9.x-compatible version exists, whether there is a replacement, or whether the site can live without it. An add-on with no v9 path is something you want to discover before the upgrade, while removing it cleanly is still easy.

Update to the latest 8.5.x

Whatever your 8.x point release, go to the end of the 8.5 line first. The 8.5.x releases contain the migrations and compatibility work that the jump to 9 assumes. Use Dashboard → System & Settings → Update Concrete, or any of the manual methods from the official upgrade guide.

If the update fails partway with a migration error about character sets (migration 20190509205043 is the one most forum threads mention), your database has mixed collations, which is common on sites that have lived through several major versions. The fix is Concrete's own CLI command:

./concrete/bin/concrete5 c5:database:charset:set utf8mb4

Run it, then re-run the update. The command-line binary is concrete5 on version 8; version 9 ships it under both names, so the commands below work before and after the core swap.

Raise PHP in stages

Concrete 9 supports PHP 7.3 through 8.5, but your custom code and add-ons might not. Do not change the core version and the PHP version in the same move; when something breaks you will not know which change broke it. The sequence that works:

1. On latest 8.5.x, move to PHP 7.4 if you are below it. Fix what surfaces.
2. Move to PHP 8.1 or newer. Fix what surfaces. This is where old custom blocks fail loudly, and loud is good; you want these errors now.
3. Only then upgrade the core to 9.

Requirements for the destination, for reference: MySQL 5.7 or later or MariaDB, InnoDB, and the usual PHP extensions (PDO MySQL, DOM, SimpleXML, mbstring, GD with FreeType, fileinfo, curl, zip, iconv).

Upgrade to the latest 9.x

Go straight to the newest 9.x; there is no need to walk through 9.0, 9.1, and so on. For a site of any size, use the command line rather than the browser, because big version jumps run many migrations and can exceed a web request's limits:

1. Back up again.
2. Enable maintenance mode:

   ./concrete/bin/concrete5 c5:config -g set concrete.maintenance_mode true

3. Replace the concrete directory with the one from the new release. Empty the updates/ directory and delete application/config/update.php if present.
4. Run the update and watch the migrations scroll by:

   ./concrete/bin/concrete5 c5:update

5. Turn maintenance mode off:

   ./concrete/bin/concrete5 c5:config -g set concrete.maintenance_mode false

If you manage the site with Composer instead of the standard distribution, the mechanics differ (you update the core dependency and run the same migration step), but the sequencing in this guide applies unchanged.

Port the theme and clean up

With the core on 9:

• Install and test the 9.x versions of your add-ons.
• Port or replace the theme. If porting: Bootstrap 3 to 5 is the bulk of it (grid classes, utilities, and every JavaScript component changed), plus namespacing everything under .ccm-page if it was not.
• Click through the dashboard and, more importantly, edit mode on your most complex pages. Rendering is the easy part; incompatibilities show up when you edit.
• Clear caches, re-run your backup routine once so you know it still works on the new layout, and only then repeat the whole run on production.

If a step fails

The failure you cannot diagnose is the one where three things changed at once. If you followed the staging order above, whatever broke is attributable to the last single step. Restore the backup you took before that step, fix the cause, and rerun. If a specific migration fails, search the exact migration ID; the forums have a decade of upgrade threads, and yours is rarely the first site to hit any given one.