Upgrade Craft CMS 2 to Craft 5: Complete Migration Guide

Prerequisites

This guide covers the complete path from Craft CMS 2/PHP 5.6 to Craft CMS 5/PHP 8.3. A span of roughly eight years of platform changes. This Craft CMS upgrade guide covers both major upgrade approaches, the specific technical requirements, and the pitfalls that trip up most teams.

One critical point upfront: direct upgrades are not supported. Craft requires stepping through major versions (2→3→4→5), though many developers choose clean rebuilds given the architectural changes involved. This legacy CMS migration process requires careful planning.

Prerequisites

Before starting, confirm you have:

Current Environment Access:

• SSH access to your existing server
• Database export capabilities (mysqldump or similar)
• Access to all source files, including custom plugins
• Documentation of any server-specific configurations

Target Environment Ready:

• PHP 8.2 or higher (8.3 recommended)
• MySQL 8.0.17 (InnoDB) or PostgreSQL 13 
• Composer 2.0 
• 512MB PHP memory limit
• SSL certificate configured

Documentation Prepared:

• List of all active plugins
• Custom module/plugin source code
• Template file inventory
• Content model documentation (sections, fields, entry types)

Backups Verified:

• Complete database backup tested for restore
• Full file system backup including assets
• Version control snapshot if using Git

Choosing Your Upgrade Path

You have two options. The right choice depends on your site's complexity and your team's priorities.

Path 1: Clean Rebuild

Craft's own documentation recommends treating Craft 2 upgrades as building a new site. This Craft CMS clean rebuild approach isn't a shortcut; it's often the most reliable approach.

Best for:

• Small-to-medium sites
• Sites with outdated or discontinued plugins
• Projects where you want to redesign the content model
• Teams with limited time for debugging version-specific issues

Typical timeline: 20-40 hours for a small business site

Path 2: Sequential Upgrade

When you must preserve an exact data model or have complex Commerce installations, you step through each version: 2→3→4→5. This Craft CMS sequential upgrade path preserves your existing architecture.

Best for:

• Sites with heavy custom plugin investment
• Complex ecommerce configurations
• Cases where the existing content model must remain unchanged
• Sites already partially updated to Craft 3

Our experience shows that Path 1 tends to be faster and produces cleaner results for most Craft 2 migrations. Path 2 makes sense when you have significant custom code that still functions and would be expensive to recreate.

Path 1: Clean Rebuild Process

Step 1: Create a New Craft 5 Project

On your target environment, run:

composer create-project craftcms/craft your-project-name

Follow the installer prompts to configure your database connection and create an admin account.

Step 2: Recreate Your Content Model

In the Craft 5 control panel, rebuild your sections, entry types, and fields. This is your opportunity to improve the content architecture.

Review your Craft 2 fields carefully. Some field types have changed:

• Matrix blocks are now "entry types" in Craft 5, a significant architectural shift
• Some third-party field types may not have Craft 5 equivalents

Document the mapping between old and new field handles. You'll need this for content migration.

Step 3: Export Content from Craft 2

Create export scripts to pull content from your Craft 2 database. JSON format works well for import scripts:

// Simple export example for Craft 2 entries
$entries = craft()->elements->getCriteria(ElementType::Entry)
    ->section('blog')
    ->find();

$export = [];
foreach ($entries as $entry) {
    $export[] = [
        'title' => $entry->title,
        'slug' => $entry->slug,
        'postDate' => $entry->postDate->format('Y-m-d H:i:s'),
        'fields' => [
            'body' => (string)$entry->body,
            'summary' => $entry->summary,
            // Map all custom fields
        ]
    ];
}

file_put_contents('blog-export.json', json_encode($export, JSON_PRETTY_PRINT));

Step 4: Import Content to Craft 5

Write import scripts or use Feed Me (if available for your content structure) to bring content into Craft 5:

// Craft 5 console command or module for import
use craft\elements\Entry;

$data = json_decode(file_get_contents('blog-export.json'), true);

foreach ($data as $item) {
    $entry = new Entry();
    $entry->sectionId = Craft::$app->sections->getSectionByHandle('blog')->id;
    $entry->typeId = /* your entry type ID */;
    $entry->title = $item['title'];
    $entry->slug = $item['slug'];
    
    $entry->setFieldValues([
        'body' => $item['fields']['body'],
        'summary' => $item['fields']['summary'],
    ]);
    
    Craft::$app->elements->saveElement($entry);
}

Step 5: Migrate Assets

Copy your asset files to the new server's asset volume locations. Update the Assets settings in Craft 5 to match your volume configuration.

For large asset libraries, rsync works well:

rsync -avz old-server:/path/to/assets/ /new-path/to/assets/

Step 6: Rebuild Templates

Twig templates from Craft 2 won't work directly in Craft 5. Craft CMS template migration requires significant rework as the syntax has changed significantly:

| Change | Craft 2 | Craft 5 |

| Macros | Available globally | Must import explicitly |

| Pagination | {% paginate %}...{% endpaginate %} | {% paginate %} (no endpaginate) |

| CSS/JS | {% includeCss %}, {% includeJs %} | {% css %}, {% js %} |

Rewrite each template, testing as you go. This is often the largest portion of rebuild work.

Path 2: Sequential Upgrade Process

Step 1: Craft 2 → Craft 3

The Craft 2 to Craft 3 upgrade is the first step. Create a new Craft 3 project and migrate:

• Install Craft 3 fresh
• Copy your license key and config files
• Export and import your database
• Update PHP to 7.0 (Craft 3 minimum)
• Run php craft setup and follow prompts
• Address template deprecations (Craft 3 uses Twig 2)

Reference: Craft 2 to 3 Upgrade Documentation

Step 2: Craft 3 → Craft 4

Before upgrading:

• Update to the latest Craft 3.x version
• Update PHP to 8.0.2 
• Fix all deprecation warnings shown in the control panel

Then:

composer require craftcms/cms:^4.0.0
php craft up

Reference: Craft 3 to 4 Upgrade Guide

Step 3: Craft 4 → Craft 5

Craft 5 includes an upgrade utility. Before starting:

• Update to the latest Craft 4.x version
• Confirm PHP 8.2 is running
• Handle database charset and collation

Run the upgrade:

composer require craftcms/cms:^5.0.0
php craft up

You may need to address charset conversion:

php craft db/convert-charset

Reference: Craft 4 to 5 Upgrade Guide

Database Migration: MySQL 8 Specifics

Craft CMS database migration to MySQL 8 Craft CMS requires attention to charset settings. Craft 5 uses different default charset and collation settings:

| Setting | Craft 5 Default |

| Charset | utf8mb4 |

| Collation | utf8mb4_0900_ai_ci |

If upgrading from MySQL 5.7, you'll need to handle this conversion. The php craft db/convert-charset command handles most cases.

For manual control, you can temporarily set charset in your .env file:

DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_0900_ai_ci

Then run the conversion and remove these environment variables after confirming success.

Teams we work with report that collation issues often surface as sorting problems, particularly with non-English content. Test thoroughly with actual content samples.

Common Mistakes to Avoid

1. Skipping major versions

You cannot jump from Craft 3 to Craft 5 directly. Craft's migration scripts depend on the previous version's schema. Attempting to skip will corrupt your database.

2. Ignoring plugin compatibility

Craft CMS plugin compatibility is critical. Check every plugin for Craft 5 support before upgrading. Many Craft 2 plugins were never updated past Craft 3. Build a spreadsheet mapping current plugins to their Craft 5 equivalents or alternatives.

3. Underestimating template work

Twig syntax changes across versions are extensive. Budget significant time for template rewrites often more than the core CMS migration itself.

4. Testing only with sample content

Real content catches edge cases. Test with a complete database dump, not a handful of sample entries.

5. Forgetting the Composer ecosystem cutoff

Craft versions prior to 3.6 may have difficulty updating dependencies after February 2025 due to changes in the Composer ecosystem. If you're on an older Craft 3 release, update to latest 3.x first.

6. Assuming MariaDB parity

Craft 5 documentation no longer recommends MariaDB for large or high-traffic sites due to "diverging parity with MySQL." If you're running MariaDB, verify compatibility or plan to switch to MySQL 8.

Testing and Verification

Before Going Live

1. Content verification

• Compare entry counts between old and new sites
• Spot-check 10-20 entries across different sections
• Verify all custom field data migrated correctly

2. Asset verification

• Confirm all images and files are accessible
• Check image transforms generate correctly
• Test PDF and document downloads

3. Template testing

• Test every unique template type
• Verify pagination works on listing pages
• Check forms submit correctly
• Test search functionality

4. Performance baseline

• Run load tests with realistic traffic patterns
• Check database query performance in the Craft debug toolbar
• Verify caching is configured and working

5. User acceptance

• Have content editors test their workflows
• Verify permissions work as expected
• Test any custom control panel additions

Post-Launch Monitoring

Keep the old site accessible (even if offline) for at least 30 days. Issues often surface when real users interact with the new system.

Watch for:

• 404 errors from changed URLs
• Broken internal links
• Missing images in older content
• Search indexing issues

Conclusion

Migrating from Craft 2/PHP 5.6 to Craft 5/PHP 8.3 requires significant planning, but the payoff is substantial: better security, improved performance (PHP 8.3 runs 5-42% faster depending on workload), and access to years of platform improvements. When you upgrade Craft CMS, you also upgrade PHP 5.6 to 8.3 for these performance gains.

For most Craft 2 sites, a clean rebuild provides the cleanest path forward. Sequential upgrades remain viable when you have complex custom code or Commerce configurations that justify the extra steps.

We recommend starting with a thorough audit of your current plugins and templates. These two areas determine which path makes sense for your project and how much work lies ahead. If you need Craft CMS migration services and want to avoid the common pitfalls, we can help you assess your current setup and choose the right approach for your timeline and budget.