How to Migrate from Drupal 7 to Drupal 10: A Step-by-Step Guide

Migrating from Drupal 7 to Drupal 10 can be time-consuming due to Drupal 7 uses a different system for storing the data than Drupal 8+, Migrating to the latest version of Drupal is essential to maintain a secure, high-performance, and future-ready website. Let’s get started step-by-step

Audit your Drupal 7 site

List all content types, fields, and custom entities.
Identify the contributed modules in use and check if they have stable versions in Drupal 10.
Note down custom code (e.g., custom modules, themes, or hooks).
Evaluate your site architecture: This is a good time to rethink your site's architecture for performance and usability improvements.

Drupal 10 Installation

In Drupal 10, you’ll use core migration modules and some contributed modules.

Enable the core migration modules:
- Migrate, Migrate Drupal, Migrate Drupal UI (if using the user interface - not recommended for complex migration)
Install the Migrate Plus and Migrate Tools modules for extended migration capabilities.

Start Migration using Drush

Make sure that the source Drupal 7 database is accessible. You will need its database credentials, such as Database name, Username, Password, and Host.

Add the database information to the settings.php file of your Drupal 10 site:

$databases['migrate']['default'] = array (
  'database' => 'drupal7_database_name',
  'username' => 'db_username',
  'password' => 'db_password',
  'host' => 'localhost',
  'driver' => 'mysql',
  'prefix' => '',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
);

Generate Migration Files (Dry Run)

Run the migrate-upgrade command to create migration configuration files. This will not import any data but will help generate the migration scripts needed

drush migrate-upgrade --legacy-db-url=mysql://db_username:db_password@localhost/drupal7_database_name --legacy-root=http://example.com --configure-only

This command will generate migration configurations (*.yml) under your config/ directory. Review these files to check the mapping of content types, fields, and terms.

List Available Migrations:

drush migrate-status

When migrating from Drupal 7 to Drupal 10, one of the significant changes is the shift from image fields to media fields. In Drupal 10, it’s recommended to use media entities to handle images and other file types.

Typical Migrating content sequence

First, migrate all images/documents to media fields
User Migration
Taxonomy migration
Paragraph Migration (if exists)
Node Migration

Let's see each content migration one by one.

Media Migration: We need to migrate images and documents first, that can be used in most of the entities in Drupal like User photos, node media field references and others. Use the d7_file source plugin to migrate all media files to Drupal 10. You can directly download the actual files from existing Drupal 7 live servers or download the entire files folder and place it on locally for a faster migration process.
User Migration: Migrating users is important before your terms and nodes migrate, because when we will need those user IDs to attach on nodes and terms author info. Use the upgrade_d7_user source plugin (use migrate upgrade command generated yml files).
Taxonomy migration: Use the Migrate-upgrade command files to migrate all your terms, each Taxonomy will have each yml to execute, upgrade_d7_taxonomy_term_<vocab_name>.yml if your site is multilingual you need to run separate migration for it.
Paragraph Migration: if your site has a paragraph or any other entity which references to node migration, write the migration yml and import and verify it.
Node Migration: Migrate your all content types nodes using the d7_node and d7_node_complete source plugin modify your each node migration yml accordingly to your content structure.

Migration Custom Modules and Template files

Custom Code Migration from Drupal 7 to Drupal 10 involves rewriting your custom modules to fit the modern framework. Key changes include converting .info files to YAML, using services and event subscribers instead of hooks, and updating routing with .routing.yml files. Additionally, any form or menu logic will need adjustments to match the class-based system in Drupal 10.

For Twig, Drupal 10 replaces PHPTemplate with Twig as the templating engine. Twig is a flexible and secure templating system, which simplifies theming by using logic directly in templates with minimal PHP.

Testing the Migration

Once the migration is complete, thoroughly test the migrated data:

Check content: Ensure that all content types, fields, and data have been correctly migrated.
Verify media: Make sure images, videos, and other media files are working correctly.
User roles and permissions: Test user accounts and permissions.
Taxonomy: Check that taxonomy terms been correctly mapped.