Drupal 12 is expected in the week of 7 December 2026, and one recently confirmed change matters particularly to organisations still running Drupal 6 or Drupal 7: the legacy Migrate Drupal and Migrate Drupal UI modules will be removed from Drupal core. Drupal 6 and 7 sites will not be able to migrate directly to Drupal 12 using the core migration path.
This is not an instruction to panic or to rebuild every legacy site immediately. It is a deadline for choosing the right intermediate target. The supported and practical route is to migrate the legacy site to Drupal 11 while the migration source plugins are still available, then perform a normal Drupal 11-to-Drupal 12 upgrade. This article presents a production-minded runbook for doing that with repeatable local builds, Drush, controlled data transformations and verification rather than a one-off import followed by guesswork.
What is changing in Drupal 12?
The change is narrower than “Drupal migration is disappearing”. Drupal 12 will still contain the Migrate API and the destination plugins required to import data into modern Drupal. What is being removed are the source migrations and supporting UI intended specifically for Drupal 6 and Drupal 7 databases. The modules are deprecated in Drupal 11 and are not being moved to a contributed project. ([drupal.org](https://www.drupal.org/docs/core-modules-and-themes/deprecated-and-obsolete?utm_source=openai))
That distinction is important. A custom migration from an external API, CSV file or legacy application can still use Drupal’s migration framework. What will no longer be available in Drupal 12 is the ready-made Drupal 6 and Drupal 7 source layer that understands legacy nodes, users, taxonomy, files, field tables and related structures.
Drupal’s current guidance is therefore straightforward: migrate Drupal 6 or Drupal 7 to Drupal 11 first, and then upgrade that Drupal 11 site to Drupal 12. Drupal 11 is scheduled to remain supported until late 2028, giving teams a useful period in which to complete the second step after the migration has stabilised. ([drupal.org](https://www.drupal.org/planet?_pxhc=1671620400098&utm_source=openai))
Choose the correct migration strategy
There are three common approaches. The first is a conventional rebuild: create a new Drupal site, model the content, migrate the data and manually recreate functionality. The second is a direct technical migration using Drupal’s legacy source plugins and a target Drupal 11 installation. The third is a hybrid, in which stable content is migrated automatically while obsolete structures, poor markup and abandoned modules are redesigned.
For most long-lived Drupal 6 and 7 sites, the hybrid approach is the most defensible. Automated migration is good at moving known data repeatedly. It is not good at deciding whether a fifteen-year-old content type, permission model or HTML fragment still belongs in the new site.
Use Drupal 11 as a migration landing zone
Do not create a Drupal 12 target and assume that a missing module can be added later. Build a Drupal 11 migration environment now, install the required migration tooling, and keep that environment reproducible in version control. Once the content and configuration are validated on Drupal 11, treat the Drupal 12 upgrade as a separate change with its own test cycle.
The Drupal 11 landing zone should be a proper application project, not a manually assembled directory copied from production. It should have:
- a committed
composer.jsonandcomposer.lock; - the same PHP major and database family intended for production;
- environment-specific settings excluded from version control;
- a private or protected copy of the legacy database and files;
- automated checks for deployment, configuration import and smoke tests;
- a documented rollback or cutover plan.
Inventory the legacy site before writing migrations
The most expensive migration errors are usually planning errors. Before creating a target site, capture what exists and decide what should survive. A database dump alone is not an inventory.
Record the source system
Document the exact Drupal version, PHP version, database engine, table prefix, public files path, private files path, multisite layout and enabled modules. Record whether the site uses contributed systems such as FileField, ImageCache, Organic Groups, Panels, Workflow, Webform or custom entity-like tables.
Also record operational behaviour. A site may appear to contain only pages and articles but still rely on cron jobs, feeds, search indexes, payment callbacks, scheduled publishing, redirects or external integrations.
Build a content disposition matrix
For every content type, field, vocabulary and user role, decide whether it will be migrated, transformed, archived or discarded. A simple CSV or spreadsheet is enough:
Legacy object Target object Decision
page.body page.body migrate and clean HTML
story.field_hero media.image transform
event.field_date event.field_start migrate and normalise timezone
old_press_release article migrate only published items
legacy_tracking_code none discard
anonymous form submissions webform_submission export for review
This prevents a migration from becoming a historical dump of every accidental field the site accumulated. It also gives content owners a clear opportunity to approve deletions before technical work makes them difficult to reverse.
Measure the data
Count nodes by type and publication state, taxonomy terms, users by role, files by directory and revisions per entity. Identify unusually large tables and invalid references. On a Drupal 7 database, useful first-pass queries might include:
SELECT type, status, COUNT(*) AS total
FROM node
GROUP BY type, status
ORDER BY type, status;
SELECT COUNT(*) AS orphaned_files
FROM file_managed fm
LEFT JOIN file_usage fu ON fu.fid = fm.fid
WHERE fu.fid IS NULL;
SELECT uid, COUNT(*) AS content_items
FROM node
GROUP BY uid
ORDER BY content_items DESC;
These queries are deliberately diagnostic rather than migration-specific. Review their results manually. A file with no recorded usage may still be linked from custom markup, and a large content count for one user may reflect an import account rather than suspicious activity.
Prepare the Drupal 11 migration environment
Perform migration work against a disposable local or staging environment. Never use the production database as the source for an experiment unless you have a verified backup and the source is treated as read-only.
Drupal’s documented Drush workflow uses the contributed Migrate Upgrade module to generate migration configuration from the legacy database. The generated migrations can then be inspected and executed individually with Drush. ([drupal.org](https://www.drupal.org/docs/upgrading-drupal/upgrading-from-drupal-6-or-drupal-7/upgrade-using-drush?utm_source=openai))
After creating the Drupal 11 project and installing the required migration modules, define the legacy database as a second connection in the target site’s settings.php. The exact credentials and driver depend on your environment, but the connection must be available under the key supplied to Drush:
$databases['default']['default'] = [
'database' => getenv('DRUPAL_DB_NAME'),
'username' => getenv('DRUPAL_DB_USER'),
'password' => getenv('DRUPAL_DB_PASSWORD'),
'prefix' => '',
'host' => getenv('DRUPAL_DB_HOST'),
'port' => getenv('DRUPAL_DB_PORT') ?: '3306',
'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
'driver' => 'mysql',
];
$databases['migrate']['default'] = [
'database' => getenv('LEGACY_DB_NAME'),
'username' => getenv('LEGACY_DB_USER'),
'password' => getenv('LEGACY_DB_PASSWORD'),
'prefix' => getenv('LEGACY_DB_PREFIX') ?: '',
'host' => getenv('LEGACY_DB_HOST'),
'port' => getenv('LEGACY_DB_PORT') ?: '3306',
'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
'driver' => 'mysql',
];
Keep credentials in environment variables or a secrets manager. Do not commit them to the repository, migration YAML files or deployment logs. Restrict the legacy database account to the permissions required for reading the source.
Generate migrations without immediately importing them:
drush migrate:upgrade \
--legacy-db-key=migrate \
--legacy-root=/srv/legacy-site \
--configure-only
drush migrate:status --tag='Drupal 7'
The --configure-only option is valuable because it separates generation from execution. You can review the resulting migration configuration, remove unwanted migrations and adjust mappings before any target entities are created. Drupal’s documentation also supports using --legacy-root to locate the source files directory; for a remote public files directory, an HTTP location may be used where appropriate, while private files should normally be made available through a controlled local path. ([drupal.org](https://www.drupal.org/docs/upgrading-drupal/upgrading-from-drupal-6-or-drupal-7/upgrade-using-drush?utm_source=openai))
Run migrations in dependency order
Do not start with nodes simply because they are the most visible content. Drupal content depends on users, roles, text formats, vocabularies, files, media and field definitions. Generated migrations contain dependencies, but a staged workflow still makes failures easier to understand.
A typical sequence is:
- system and configuration prerequisites;
- users, roles and permissions;
- filter formats and text-processing configuration;
- taxonomy vocabularies and terms;
- files and images;
- content types and field definitions;
- nodes and revisions;
- comments, references and dependent entities;
- aliases, redirects and site-specific custom data.
Inspect the available migrations before running them:
drush migrate:status --tag='Drupal 7'
drush migrate:tree --tag='Drupal 7'
Run a small, representative import first. A pilot should include at least one item from every important content type, a file, an image, a taxonomy reference, an unpublished item and a revision if revisions matter to the editorial process.
drush migrate:import upgrade_d7_taxonomy_vocabulary
drush migrate:import upgrade_d7_taxonomy_term
drush migrate:import upgrade_d7_node_type
drush migrate:import upgrade_d7_node --limit=25
drush migrate:messages upgrade_d7_node
Migration IDs vary with the source version and generated configuration, so copy them from drush migrate:status rather than assuming that every site has identical IDs. The same applies to the tags and groups used by custom migrations.
Once the pilot is understood, run the selected set. For a repeatable process, prefer explicit tags or groups over blindly importing everything:
drush migrate:import --tag='Drupal 7' --continue-on-failure
drush migrate:status --tag='Drupal 7'
drush migrate:messages upgrade_d7_node
The --continue-on-failure option allows a broader test run to complete while recording failures for later investigation. It should not be treated as permission to ignore errors before launch. A migration with hundreds of failed rows is not a successful migration merely because the command returned control to the shell.
Handle custom fields and transformations deliberately
Core migration paths cover common Drupal entities, but real sites often contain custom field storage, bespoke modules and content encoded in markup. Use generated configuration as a starting point, not as a final specification.
Typical transformations include:
- combining several legacy fields into one structured field;
- converting image or file references into Media entities;
- normalising dates into a defined timezone;
- mapping old user roles to a smaller modern role set;
- turning HTML tables or embedded tokens into structured content;
- dropping obsolete tracking, presentation and integration fields;
- rewriting internal links and legacy file URLs.
For a custom migration, process plugins can make transformations explicit. The following example illustrates the shape of a migration definition, not a universal mapping. The source field names and destination field names must match the actual site:
id: legacy_article
label: 'Import selected legacy articles'
migration_group: legacy_content
source:
plugin: d7_node
node_type: legacy_article
process:
title: title
body/value:
plugin: callback
callable: strip_tags
source: body/0/value
body/format:
plugin: default_value
default_value: basic_html
status: status
uid:
plugin: migration_lookup
migration: upgrade_d7_user
source: uid
destination:
plugin: 'entity:node'
default_bundle: article
migration_dependencies:
required:
- upgrade_d7_user
Be cautious with destructive processing such as strip_tags. It may be appropriate for a plain-text field but damaging for editorial body content. In production migrations, use a purpose-built process plugin or a carefully tested callback that preserves permitted markup, resolves links and records rows requiring manual review.
Files, URLs and revisions deserve separate testing
File migrations are frequent sources of “mostly works” launches. Check public and private files separately, verify stream wrappers, confirm file ownership and test files with spaces, non-ASCII names, duplicate basenames and missing originals.
After importing files, test representative URLs from the browser and from the command line. Do not rely only on database counts:
curl -I https://staging.example.test/sites/default/files/example.pdf
curl -I https://staging.example.test/sites/default/files/styles/large/public/example.jpg
Legacy aliases and redirects should be treated as SEO and user-experience data, not as optional decoration. Export a URL inventory from the old site, compare it with the new alias structure, and create redirects for changed high-value paths. Test canonical links, language prefixes, trailing-slash behaviour and query-string handling.
Revisions require an explicit decision. Migrating every historical revision may be essential for regulated content, but it increases runtime and storage. If the business only needs the latest published version, document that decision and preserve the source backup according to the organisation’s retention policy.
Validation: compare behaviour, not just row counts
A migration is ready for a production rehearsal when it passes several independent checks:
- all planned content types and fields are present;
- published and unpublished states match the approved rules;
- authors and ownership are mapped correctly;
- taxonomy references resolve to the intended terms;
- images and downloads work through their public URLs;
- internal links do not point back to the legacy domain;
- search indexing excludes drafts and private content;
- editorial workflows work with real user roles;
- cron, queues, mail and integrations behave as expected;
- the site passes accessibility, security and performance smoke tests.
Automate what can be automated. A simple content audit can export selected fields from both systems and compare counts, IDs, titles, publication states and URL paths. For rendered pages, compare status codes, canonical URLs, page titles and key text rather than demanding byte-for-byte HTML equality; a modern theme will legitimately produce different markup.
Use migration messages as a work queue. The documented Drush commands include migrate:messages for inspecting failures, while migrate:rollback can undo test imports when the migration supports a clean rollback. A migration that fails can also remain locked in an “Importing” state; migrate:reset-status is available for clearing that state during controlled development work. ([drupal.org](https://www.drupal.org/docs/drupal-apis/migrate-api/debugging-migrations?utm_source=openai))
Plan the cutover and the later Drupal 12 upgrade
Once the Drupal 11 migration is stable, freeze the source site briefly, take a final database and files backup, run the final import, reconcile content created during testing and complete an acceptance check with editors. If the site remains editable during the migration period, establish a delta strategy: a second import, a content freeze window or a defined manual reconciliation process.
Keep the Drupal 11 site current after launch. Do not treat it as a disposable bridge that can be ignored until Drupal 12. Regular updates reduce the eventual upgrade gap and make it easier to identify contributed modules that have not yet declared compatibility.
For the Drupal 12 preparation phase, use the project’s upgrade documentation and compatibility tools. Drupal’s current upgrade guidance identifies Migrate Drupal and Migrate Drupal UI as removed extensions and recommends resolving those dependencies before the code upgrade. It also recommends command-line access, Composer, Drush and a development-first workflow. ([drupal.org](https://www.drupal.org/docs/upgrading-drupal/upgrading-drupal/how-to-upgrade-from-drupal-11-to-drupal-12?utm_source=openai))
A useful preparation check is:
composer show --direct
composer outdated "drupal/*"
drush status
drush updatedb:status
drush config:status
composer why-not drupal/core ^12
The final command is useful for identifying dependency constraints, but it is not a substitute for reading release notes, checking custom code and testing the application. Review contributed modules, themes, patches and Composer plugins individually. Pay particular attention to custom code that calls deprecated APIs or assumes Drupal 11-only behaviour.
Security and governance considerations
Legacy migration environments contain real personal data, credentials, unpublished material and potentially vulnerable code. Use access controls, encrypted storage and a documented retention policy. Sanitise or pseudonymise data where a full production copy is not necessary. Remove imported API keys and rotate credentials if they have ever been stored in the legacy database.
Keep the source site isolated from the public internet where possible during migration testing. Do not expose a copied Drupal 7 database through a publicly reachable development URL. Apply network restrictions, basic authentication and appropriate web-server rules, and ensure that search engines cannot index staging environments.
Migration code is application code. Review it, test it and commit it. Avoid ad hoc SQL updates against the target database when a migration process plugin, post-import hook or update routine can express the transformation safely. If a manual correction is unavoidable, record the exact query, affected rows and rollback procedure.
Conclusion
The removal of the Drupal 6 and 7 migration modules from Drupal 12 is best understood as a planning signal. The migration path is not disappearing today, but the safe landing zone is Drupal 11, and the time to establish a repeatable migration process is before the Drupal 12 release window in December 2026.
Start with an inventory, decide what deserves to survive, build a Composer-managed Drupal 11 target and generate migrations without importing them immediately. Run a representative pilot, fix mappings through code, validate behaviour rather than only record counts, rehearse the cutover and keep the resulting Drupal 11 site maintained. Once that foundation is sound, the later Drupal 12 upgrade becomes a normal compatibility and deployment exercise instead of a race to recover a migration tool that is no longer part of core.