Drupalwoo ☉

Moving From Drupal 7 To Drupal 10 With Migration Tools

Moving a Drupal 7 website to Drupal 10 is a migration project rather than a conventional core upgrade. Drupal 7 and Drupal 10 use different APIs, configuration systems, database structures, field definitions and theme architectures. The safest process creates a clean Drupal 10 site, connects it to the old database, and imports selected content through Drupal’s Migrate API.

This approach gives developers control over what comes across and what should be redesigned. It also creates an opportunity to remove obsolete fields, consolidate content types, improve accessibility and replace unsupported modules. For an Australian organisation, that may include reviewing suburb and postcode data, Australian Government accessibility expectations, privacy settings under the Privacy Act and hosting arrangements in Sydney, Melbourne or another local data centre.

Approach Suitable For Main Benefit Main Risk
Drupal migration tools Structured D7 content, users, taxonomy and files Repeatable imports with mapping and rollback options Requires preparation and testing
Manual content recreation Small sites with limited pages Clean editorial structure Slow and easy to perform inconsistently
Custom scripts Unusual data or external systems Precise control over transformations Higher development and maintenance cost
Partial migration Sites retaining only selected content Reduces legacy data and technical debt Requires clear archival and redirect decisions

Treat The Project As A Rebuild

A Drupal 7 to Drupal 10 migration should begin with a target-state design. Drupal 10 is not a drop-in replacement for Drupal 7, so copying the old database into a new installation will not produce a supported website. Core tables, contributed modules, theme files and configuration values need to be handled through compatible migration processes.

The Migrate API represents source data as entities, fields and relationships. Drupal’s migration definitions then transform that source into nodes, users, taxonomy terms, media entities and files in the destination site. This makes it possible to change a content type during import, split one old field into several new fields or discard values that no longer serve the organisation.

Document the desired Drupal 10 model before writing migration code. List each content type, field, vocabulary, media bundle, user role and menu that will remain. A community organisation in Brisbane may decide to merge several event content types into one, while a Sydney consultancy may retain separate case studies, services and staff profiles. Those decisions determine the migration work more accurately than the existing Drupal 7 database does.

Audit And Prepare The Drupal 7 Source

Start with a full inventory of the current website. Record enabled modules, custom modules, themes, content counts, language settings, image styles, private files, URL aliases, redirects, users and cron tasks. Tools such as Upgrade Status can identify modules and themes that have Drupal 8, 9 or 10 versions, but its results are a starting point rather than a migration plan.

Remove abandoned content and unused configuration before the final export. Check duplicate taxonomy terms, unpublished drafts, broken file references and accounts belonging to former staff. Pay special attention to Australian address fields: an old free-text “State” field may contain NSW, New South Wales and “N.S.W.” in the same column, requiring a normalisation rule before import.

Create a complete backup of the Drupal 7 database and files, then test restoring it. Keep the production site available while the migration is developed, but use a staging copy for repeated imports. The source database must be reachable by the destination environment, either through a second database connection or a temporary database server. Never give a migration process more access than it needs.

Build A Clean Drupal 10 Destination

Install the latest supported Drupal 10 release in a separate codebase. Use Composer to manage Drupal core and contributed packages, and select a PHP version supported by that release, commonly PHP 8.1 or later. Drupal 7 sites often run on older PHP versions, so the old application and the new application may need separate hosting environments.

Enable the migration components required by the chosen workflow. Core modules commonly include Migrate, Migrate Drupal and Migrate Drupal UI. The Migrate Upgrade project can provide command-line helpers for generating migration configuration, depending on the Drupal and Drush versions in use. Check the installed version’s command list with Drush rather than relying on commands copied from an older tutorial.

Configure the new site’s settings, trusted host patterns, file systems and database connections before importing anything. If the migration uses a database key such as migrate, define that connection in settings.php and confirm that the destination can read the Drupal 7 schema. Copying the public and private files into a temporary location can help preserve file metadata while keeping the live site untouched.

Generate And Run Migration Definitions

Drupal’s migration tools can generate a set of migration definitions from a Drupal 7 database. The browser-based upgrade interface is useful for straightforward sites, while Drush is better for repeatable development and larger imports. A typical command may resemble drush migrate:upgrade, but the exact options depend on the installed Migrate Upgrade and Drush versions.

Use drush migrate:status to inspect available migrations before importing. Names commonly identify nodes, users, taxonomy terms, files, comments, menu links and fields. Run small groups first, such as taxonomy and files, followed by users and content. This makes errors easier to identify than importing the entire site in one operation.

Migration definitions contain source, process and destination sections. The source describes the Drupal 7 table or entity query. The process section maps and transforms values, and the destination identifies the Drupal 10 entity type and bundle. Process plugins can concatenate values, provide defaults, look up referenced entities, convert text formats and skip records that no longer meet the project’s rules.

Use migration groups and tags to organise related imports. A test run should be disposable, allowing the destination database to be rebuilt and the same imports to run again. When a migration fails, inspect the message with Drush, correct the mapping or source data, and rerun the affected migration. Avoid editing imported records manually until the mapping is stable, since manual changes can be overwritten during the next import.

Map Content, Users And Media Carefully

Content migration is usually the largest part of the project. Import referenced data before dependent content: taxonomy terms should generally exist before nodes that reference them, and files should be available before media entities are created. Drupal’s migration dependencies help define this order, although custom migrations may need explicit dependency settings.

Drupal 7 image fields often migrate into Drupal 10 media references rather than remaining simple file fields. Decide whether an old image becomes an Image media entity, a document media entity or a deliberately ignored file. Check image styles separately because style names and effects may have changed. Test original files, alt text, titles and responsive image output on real pages.

User migration needs particular care. Password hashes may be migrated when the supported process allows it, but test authentication thoroughly and plan a password reset if required. Review roles and permissions rather than copying every old permission blindly. Disable obsolete accounts, protect administrator access and confirm that personal information is handled in line with the Australian Privacy Principles.

URL aliases and redirects deserve their own migration tests. Preserve high-value paths where practical, then create 301 redirects for changed URLs. Search Console data, analytics reports and server logs can reveal which legacy pages matter most. A Victorian not-for-profit may have years of links from government directories, while an Adelaide business may rely heavily on local service pages and suburb-based searches.

Validate The Imported Website

A successful migration command does not prove that the website is ready. Compare source and destination counts for each content type, vocabulary, media bundle, user group and menu. Sample old and new records across published, unpublished, scheduled and multilingual content. Check that dates, authors, revisions, moderation states and text formats retain their intended meaning.

Test forms, search, exposed filters, breadcrumbs, navigation, XML sitemaps, RSS feeds and email notifications. Confirm that cron runs and that queues finish without errors. Review PHP and Drupal logs for missing plugins, invalid field values, broken entity references and file permission problems. Test on current Chrome, Firefox, Safari and mobile devices, including slower connections that are still common outside major Australian cities.

Accessibility should be validated during migration rather than left to the final week. Check heading order, link text, keyboard focus, colour contrast, form labels, error messages and alternative text. Public-sector and education websites may need to meet WCAG expectations under Australian procurement and accessibility requirements, so a visual comparison alone is insufficient.

Plan The Cutover And Ongoing Maintenance

Before launch, reduce the final content freeze window by rehearsing the full migration. Record the import duration, database size, file transfer time and any manual corrections. An organisation operating across Perth, Darwin and eastern states should schedule the cutover with time-zone differences in mind, rather than assuming every stakeholder works on AEST.

Prepare DNS, SSL, caching, backups, monitoring and rollback procedures. Keep the Drupal 7 site available in read-only mode until the Drupal 10 site has passed post-launch checks. If the domain is a .com.au address, verify registrar access and DNS TTL settings well before the change. Hosting in Australia may help with support hours and data residency preferences, but it does not replace application-level security and backup testing.

After launch, monitor redirects, 404 responses, login failures, queued migrations and search indexing. Review analytics for sudden drops in landing-page traffic. Update the Drupal 10 codebase through Composer, apply security releases promptly and document custom migration plugins for future maintainers. Drupal 7 reached its official end of life in January 2025, so leaving the old site exposed after cutover creates avoidable security and operational risk.

Practical Migration Checks

Use these checks to keep the work controlled and repeatable:

A disciplined migration gives the new Drupal 10 site a cleaner information architecture, predictable deployment process and safer long-term maintenance path. The migration tools handle repetitive data movement, while developers retain control over the decisions that matter: what to preserve, what to transform and what to leave behind.