Reliable Drupal migration means building a new site for the new major version and moving content, files, and functionality into it. Safety comes from full backups, repeatable imports, and testing in a staging environment before launch. A Drupal migration moves content types, fields, files, users, and configuration from an old Drupal release to a new one. The work is urgent for older sites because Drupal.org reports that Drupal 7 reached end of life on January 5, 2025 and no longer receives official updates, according to the Drupal.org core release schedule.
Table of Contents
- Build new instead of upgrading in place
- Audit modules and clean the source site
- Back up everything before changing core
- Run repeatable imports until results validate
- Plan performance and post-migration checks
Build new instead of upgrading in place
A major Drupal upgrade requires a fresh site build and migration of content, files, and modules. Pantheon Docs directs teams to build new rather than upgrade inside the existing site, according to the Pantheon update guide.
That approach isolates old configuration and lets the team rebuild themes, layouts, and custom code cleanly. It also makes bad imports easier to discard and rerun without harming the live site.
Audit modules and clean the source site
Start by listing every module, theme, and custom integration. Check each project with the Upgrade Status module, which Drupal.org provides to report availability and code compatibility for newer core versions.
Pantheon preparation guidance also calls for reviewing known-issues lists, confirming PHP-version compatibility, clearing caches, and removing unneeded code, database tables, and files. A smaller, cleaner source database migrates faster and produces fewer mapping errors.
Back up everything before changing core
Take a complete backup before any core update or migration step. Drupal.org documentation directs teams to use Backup and Migrate or Drush so the site can return to working order after failure, according to the Drupal.org Composer update guide.
Store the backup apart from the server being changed. Confirm that files, database, and configuration are all included before proceeding.
Run repeatable imports until results validate
Drupal's Migrate API supports imports that can run again after fixes. Drupal.org explains that `drush migrate:import` runs a migration while `drush migrate:rollback` removes imported items, according to the Drupal.org migration debugging guide.
Review content types and field mappings by exporting configuration to YML files. Pantheon guidance notes that complex sites should expect to script migrations and rerun them with Drush until results validate.
- Map each old field to its new destination and check required fields
- Rerun a fixed migration after rollback rather than patching live content
- Keep migration scripts under version control for review
Plan performance and post-migration checks
Very large migrations can exhaust platform memory limits and fail. Pantheon documentation ties batching, performance planning, staging-environment testing, and post-migration testing to practical safety value.
Move large file sets and long content lists in smaller batches. Test links, media, forms, redirects, permissions, and search on staging, then repeat key checks after launch.
