Why Drupal 7 media needs its own migration plan
If your Drupal 7 site stores images, documents and videos as managed files or Media entities, those assets need a dedicated migration plan, because Drupal 7 cannot be updated in place to a current release. Drupal.org documentation says Drupal 6 and 7 sites are moved into a new site with the core Migrate, Migrate Drupal and Migrate Drupal UI modules or with Drush, and the themes must be rebuilt. Media does not come across as a side effect of that core path alone, so you need to decide how each asset type will land on the new site before the content move starts. Drupal 7 security support ended on January 5, 2025, so the work is also time-bound for any site still in production.
Three kinds of media data need separate handling. Plain managed files sit in the file table and the public or private file system, and their paths must be preserved or mapped. Drupal 7 Media items are fieldable entities with their own bundles and view modes, which must be recreated as Drupal Media types. Body text is the third case: editors often embedded media through tokens or embed markup in long text fields, and those references break unless they are rewritten to point at the new Media entities. Each layer needs its own mapping, test pass and sign-off, and a missed token will not show up as an error during the run.
The Media Migration module, which covers Drupal 7 managed files and media items, is in alpha stability with no supported stable release, and its project page warns that breaking changes can arrive between alpha releases. Treat it as a tool to be pinned, tested and reviewed, not as a dependable dependency. Ask your implementation partner which release they will pin, how they will reproduce results if the module changes, and what fallback they hold for assets the module does not handle. Effort for this work is driven mainly by the volume of embedded media and the number of custom media bundles, so inventory both before you agree a scope.
Which Drupal 7 file and media features map to Drupal Media
This table compares each Drupal 7 file and media feature with its Drupal Media equivalent and notes what the migration covers and what needs checking or rebuilding by hand. Read each row as a planning question: the Media Migration module is alpha, so every row needs verification on a staging copy before cutover.
| Drupal 7 feature | Drupal Media equivalent | Migration note | Check or rebuild by hand |
|---|---|---|---|
| Managed files (file_managed records) | File entities, used as the base for Media items | Media Migration provides a path for Drupal 7 managed files, but it is alpha and has no stable release. | Confirm each file record, MIME type and owner is present after the run; spot-check a sample across file types. |
| Drupal 7 media items | Media entities with a media type | Covered by the Media Migration path for Drupal 7 media items; mapping depends on the media types you define on the target. | Define target media types first, then confirm each source item lands in the intended type. |
| Embedded media tokens in body text | Embedded media in text fields (embed or entity reference markup) | Tokens such as media embed codes in body text are not a verified one-to-one conversion in the supplied facts. | Search every text field and revision for tokens; rewrite or re-embed each one and check rendering on the front end. |
| Image fields | Image media or image fields on content types | The migration path must be checked against your field configuration, including alt text and title attributes. | Verify alt text, title, dimensions and crops; confirm image styles regenerate. |
| File fields | File media or file fields on content types | Attachment fields need a deliberate target: a media reference or a plain file field. | Confirm links to attachments, descriptions and display formatters on each content type. |
| Public and private file storage paths | Stream wrapper URIs and the target file system configuration | Source paths such as public:// or private:// must resolve on the new site, and files must be copied to the target storage. | Copy the files, check permissions for private files and test that every URL resolves after the move. |
| Revisions and translations of media | Media revisions and translated media entities | Revision and translation handling depends on the source configuration and must be tested rather than assumed. | Compare the latest revision and each translation against the source for a set of sample nodes. |
| Rollback and repeat runs | Migration map and rollback handling | Because the module warns of possible breaking changes between alpha releases, a run may need to be repeated on a new version. | Pin the module version, rehearse the full run on a copy of production and document the rollback steps. |
Documented import paths for Drupal 7 files and media
Drupal 7 files and media can move through two routes: the documented core migration path that carries sites from Drupal 6 or 7 into a new Drupal site, and the Media Migration project that maps Drupal 7 managed files and media items into Drupal Media entities. The cards below set out what each route covers, where it stops, and what to confirm before a plan is written.
Core Migrate and Migrate Drupal
The core Migrate API, Migrate Drupal and Migrate Drupal UI modules form the documented route for moving a Drupal 6 or 7 site into a new Drupal site. Drupal 7 sites cannot be updated in place, so file entities and their field references are read from the old database and written into the new one. Check which file and image fields are carried across, how public and private file paths are mapped, and whether the target Drupal core version is still supported at the time of the move.
Drush-driven migration runs
Drupal.org documents running the migration with Drush as an alternative to the user interface. For file-heavy sites, command-line runs are easier to repeat, log and time, and they suit staged test runs against a copy of production. Plan for the file system copy as a separate step, since migration reads database records but the binary files must already be present at the paths the new site expects.
Media Migration for Drupal 7 media
The Media Migration project provides a path that converts Drupal 7 managed files and media items into Drupal Media entities. Teams with Media fields, embedded media, or a library of reusable assets should evaluate it because the core route does not turn every file into a Media entity. Review which media bundles and display modes your content relies on before choosing this path.
Alpha stability warning
The Media Migration module is in alpha stability and has no supported stable release, and its maintainers warn that breaking changes can occur between alpha releases. Treat any plan that depends on it as carrying schedule and rework risk. Pin a specific tested version, record it in your build, and keep a rollback point so a later release does not change the result of a rehearsed run.
Confirm version and core compatibility
Before planning, confirm the current Media Migration version, the Drupal core versions it supports, and any open issues affecting file paths or embedded media on the project page. Compatibility with Drupal 10 and Drupal 11 should be checked against the release you intend to run, because core and contributed releases move at different times. Record the answers in the migration plan with the date you checked them.
Scope the core and contributed split
Decide which assets go through the core route and which go through Media Migration before any mapping starts. A split plan needs a clear owner for each content type, a shared file path convention, and a check that no file is migrated twice. Run both paths against the same staging copy so that reference counts and file usage agree at the end of the rehearsal.
How the migration runs from inventory to decommissioning
The sequence moves Drupal 7 files and media from an inventory of what exists through a rehearsed copy, a parallel run and a controlled cutover, so the team can retire the old site with evidence that the new one holds the same content.
Inventory files, media types and tokens
Your team and DeployOpen list every managed file, Drupal 7 media item, file field and file storage path, then search body text and other fields for embedded media tokens. The output is a register that maps each source entity to its destination media type, its file location and any content that references it. Sign-off comes from the content owner and the site lead that the register covers every content type in use. Ask the partner to show how orphaned files and unused media are counted before the list is accepted.
Confirm the Media Migration module status
Before any build, the team checks the Media Migration module's project page on Drupal.org against the planned Drupal core version. The module is in alpha with no supported stable release and may introduce breaking changes between alpha releases, so the pinned version must be recorded in the build. The security lead signs off that the team accepts that risk, and that a fallback approach, such as scripted file moves, has been scoped if the module does not cover a media type.
Build the mapping and run a pilot on a copy
DeployOpen builds the migration on a copy of the Drupal 7 database and file system, with a target site on the current Drupal core release. The pilot moves a representative sample covering each media type, each file field and a set of body text tokens, then records what converted and what did not. Acceptance requires the content owner to confirm that sampled items render correctly and that token references resolve to the new media entities.
Repeat full test runs with rollback
The team runs complete migrations against fresh copies of the source, timing each run, comparing counts of files, media entities and references, and checking file paths on disk. Each run is rolled back and rerun to prove that the rollback leaves no orphaned files or entities. The migration lead signs off when two consecutive full runs produce the same counts and no unresolved token errors remain in the reports.
Verify content and file integrity
Automated checks compare checksums of migrated files with the source, test that every migrated media entity loads, and review a stratified sample of pages in the browser. Editors verify captions, alt text, licensing notes and image styles, which often do not carry over without explicit mapping. The QA lead signs off on a written defect list with each item either fixed or accepted by the content owner.
Run the old and new sites in parallel
For a defined period agreed in advance, editors work on the Drupal 7 site and the new site receives a final incremental sync, or the team agrees a content freeze. Support staff compare how items display on both platforms and log differences. Sign-off is given by the business owner when the parallel log shows no open defects affecting published content and the rollback procedure has been rehearsed one more time.
Cut over and retire the Drupal 7 site
The team freezes writes on the Drupal 7 site, runs the final migration, switches DNS or the reverse proxy to the new site, and confirms redirects and file URLs respond correctly. The old site is kept read-only and its database and file store are archived with a documented restore path. Decommissioning is signed off once the archive is verified, access to the old server is removed and the archive location is recorded in the handover pack.
How embedded media tokens and file paths are handled
Drupal 7 sites often embed files and media in body text using media tokens, which the editor expands at render time. Those tokens are not the same thing as a Drupal Media reference, so after migration the text can still contain the old markup while the file itself has moved. The Media Migration module is designed to map Drupal 7 managed files and media items to Drupal Media entities, but whether a given token form is rewritten inside body text depends on the markup in your content and the module version you test against. Confirm this with a sample of real nodes, not the module description.
- Inventory the token forms: Search body fields for the tokens and inline file markup your site actually uses, grouped by text format.
- Test a representative node set: Include nodes with embedded images, documents, video, and tokens inside lists, tables, and summaries.
- Compare rendered output: Check that each embed renders the expected Media view mode on the new site, not a broken placeholder.
- Track unresolved references: Log every token that still points to a file ID with no Media entity so the list can be worked by hand.
- Plan manual rewrites: Where the import does not carry a token, edit the body text or rebuild the embed with the Media library, and record each change.
Because the module is in alpha and may change between releases, rerun the token checks on every test migration, not only the first.
Existing URLs to files, such as images linked from search engines, partner sites, or old PDFs, are often what breaks first. Drupal 7 stored managed files under a public or private file directory with a path that the new site may not reproduce exactly. Keeping those paths working means deciding, before the cutover, whether the new site will keep the same directory layout, serve files from a new location with redirects, or both. This decision also affects storage on the infrastructure you control and how the web server handles requests.
- Record the current path pattern: Document the public and private file directories and any stream wrappers the site uses.
- Decide the target layout: Choose whether to preserve the path, rewrite it, or move files to object storage with a stable public URL.
- Build a redirect map: Generate old-to-new file URLs from the migration mapping and load them into the web server or redirect module you use.
- Test with real links: Request a sample of old file URLs from outside the network and confirm the status code and content type.
- Keep private files private: Confirm that access checks still apply to files that were private in Drupal 7 after the move.
Recheck redirects after the final content sync, since files added late in the project may not be in the map you tested.
Media is often referenced by more than one entity, such as a document used in a node, a taxonomy term image, a user picture, and a block. Each reference type stores the link differently, so a migration that handles nodes correctly can still leave term images or user pictures empty. Treat every entity type that holds a file reference as its own item in the test plan, and confirm which of them the Media Migration module covers before you rely on it.
- List every file-bearing field: Include nodes, taxonomy terms, users, blocks, custom entities and comments, not only content types.
- Check shared media: Confirm that one Drupal 7 file used by several entities becomes one Media entity with several references.
- Verify field types: Make sure image and file fields land on the Media fields your content types expect, including alt text and captions.
- Test display: Look at views, teasers and blocks that show media from other entities, since these are often missed.
- Rebuild gaps by hand: Where a reference does not carry over, reattach the Media entity through the field and note it in the cutover checklist.
Ask your implementation partner to show the counts from each entity type in the test report, so gaps are visible before cutover.
What usually goes wrong with media migrations
Media migrations from Drupal 7 rarely fail in one dramatic step. They fail through small losses: a token that no longer resolves, a file that stayed behind on the old server, or an alt text field that was never mapped. The cards below cover the failure points we see most often and how to plan around each one.
Alpha module changes between releases
Media Migration has no supported stable release and warns that breaking changes can land between alpha versions. A mapping that worked in one release can change field names or entity handling in the next. Pin one exact version in your build, record it in the migration plan, and rerun your full test migration after any upgrade of that module. Confirm the current release notes before you start.
Broken embedded media tokens
Drupal 7 body text often holds embedded media tokens that point to file IDs. If those IDs are not remapped to the new Media entity IDs, editors see empty blocks or raw markup on live pages. Scan every text field, including revisions and summaries, for tokens before and after the run. Count tokens in the source and confirm each one resolves on the target.
Missing or moved files
Files can be referenced in the database but absent from the new file system, especially when public and private paths differ or when files were stored outside the default directory. A migration can report success while images return 404 errors. Copy the file directory as part of the cutover, then compare the file count and checksums against the source. Check private files separately, since their access rules are different.
Broken links and image paths
Old file paths such as sites/default/files URLs can remain hard-coded in body text, menus and theme templates. These links often survive the migration unnoticed and break when the storage location or domain changes. Search the database and the codebase for old paths, rewrite them to the new Media URLs or a redirect rule, and crawl the staging site to confirm that no internal asset returns an error.
Lost alt text and file metadata
Accessibility attributes and descriptive fields are easy to drop when Media fields are mapped without review. Alt text, titles, captions, copyright notes and author credits may exist in Drupal 7 field data but not in the new Media fields. Map each source field to a named target field before the run, then sample items in each media bundle to confirm the values arrived intact.
Staying on Drupal 7 too long
Drupal 7 security support ended on January 5, 2025, so every month on the old site adds unpatched exposure. Extended support from certified vendors can buy time, but it does not make the migration easier, and it adds a recurring cost. Set a cutover date that includes media testing, and ask any extended support provider how long coverage lasts for your site before you rely on it.
What drives the effort and cost of the media work
This table compares the main drivers of Drupal 7 file and Media migration effort, showing whether each cost is one-time or recurring and what to request in a written quote. Read it before scoping, because the first two drivers usually set the size of the mapping and validation work.
| Driver | Why it changes effort | One-time or recurring | What to ask for in a quote |
|---|---|---|---|
| Number and types of files and media items | More file types and entity bundles mean more mapping rules and more sample sets to check. | One-time | Counts by file type and by media bundle, and which bundles map to which Media types. |
| Body fields with embedded media tokens | Each text format and body field that uses tokens needs its references rewritten to Media entities. | One-time | A list of content types and text formats that contain tokens, with a sample of each. |
| Custom file storage schemes | Non-default stream wrappers or custom paths require extra path resolution before files can be copied. | One-time | A description of each scheme, where files live today, and how they are reached from the new site. |
| Remote or private file handling | Remote sources need fetching and retry logic, and private files need access rules carried over. | One-time, with ongoing access checks until cutover | How remote and private files are sourced, credentials needed, and who approves access rules. |
| Translation and revisions | Translated file fields and revision history multiply the records to map and verify. | One-time | Whether translated media and older revisions must migrate, and the languages in scope. |
| Validation required by the business | Checks range from spot sampling to full file hash and link comparison, and the depth changes test time. | One-time, plus repeat runs for each alpha release retested | The validation method, the sample size agreed, and the sign-off owner. |
| Module stability and rework | Media Migration is alpha with possible breaking changes, so upgrades of the module can force re-runs and fixes. | Recurring while the module stays in alpha | How many migration rehearsals are included and how module upgrades during the project are handled. |
| Ongoing support after cutover | Broken media links often surface weeks after launch, so fixes need a support window. | Recurring | Response scope, the period covered, and whether post-launch link fixes are included in the fixed scope. |
Questions teams ask before a Drupal 7 media migration
How much does a Drupal 7 media migration cost?
No price can be given here because cost depends on the size of the file and media estate, how many media types and fields need mapping, and how many embedded media references sit in body text. The main cost components are planning and inventory, the migration build and test runs, rebuilding media display in the new theme, and review of migrated content by your editors. Some of this is one-time project work, while hosting, storage and any ongoing module maintenance recur. Ask for a quote built from a written scope that states the inventory results, the number of media types, the sites involved and the acceptance checks. Compare quotes on what each one includes, not only on the total.
How long does a Drupal 7 media migration take?
The duration depends mainly on how varied your media is and how much content must be checked. Timing is driven by the number of media types, the volume of files and the number of body fields that contain embedded media tokens, plus the time needed for editors to verify results. Repeated test runs against a copy of the production database add time, as does any dependence on the alpha-stage module. Ask any partner for a phased timeline with named milestones and a test cycle, and ask which assumptions about content volume and editor review the timeline depends on.
What does our internal team need to provide?
Your team needs to provide access to the Drupal 7 site and its database, a list of the media types and file fields in use, and the storage locations of the managed files. Content owners should name the body fields that embed media and identify content that must be kept exactly as it is. You also need a staging environment for test runs, a person who can approve acceptance criteria, and editors who can review migrated media on the new site. Confirm the exact access and approvals with your partner before the scope is signed, since these items often determine the schedule.
Can our own team run a Drupal 7 media migration without a partner?
Yes, a capable Drupal team can attempt the work, but it requires experience with the Migrate API, custom migration code and Drupal media configuration. The Drupal.org documentation says Drupal 6 and 7 sites are migrated into a new site and themes must be rebuilt, so the media work is only one part of a larger upgrade. Assess your team's skills, the time it can spare and the number of media types and embedded references. A partner can take on the build and testing, while your team keeps ownership of content decisions and acceptance. Either way, plan for test runs before any cutover.
Is the alpha Media Migration module safe to use?
The module is not safe to treat as a finished tool. Media Migration is in alpha stability, has no supported stable release and warns that breaking changes may occur between alpha releases. That means you should pin a specific version, test every run on a copy of production data and keep the Drupal 7 site intact until acceptance is complete. Plan for the possibility of custom code to fill gaps, and confirm the module's current status on its Drupal.org project page before you start. Budget time for fixing issues that the module does not handle.
What happens to the Drupal 7 site during the parallel run?
The Drupal 7 site normally stays live and editable while the new Drupal site is built and tested, so content created during that period must be captured in later incremental runs or re-checked by hand. Drupal 7 security support ended on January 5, 2025, according to Drupal.org, so the old site carries ongoing security exposure. The Drupal Association lists HeroDevs and Tag1 Consulting as certified extended security support vendors for sites that cannot migrate yet. Agree in writing who freezes content, when the final migration runs and how rollback works if acceptance fails.
Who owns the migrated files and media after the project?
Your organization owns the content, files and site it runs, because Drupal and contributed modules are licensed under GPL-2.0-or-later and there is no paid edition of Drupal itself. The migration scripts and any custom modules should be delivered as code in your repository, documented, and handed over with the test records. Ask your partner to confirm the handover items, including the migration scripts, the inventory and the acceptance evidence. Ongoing support for the new site is a separate decision and can be arranged as a retainer.
Official Drupal sources for this migration
Start with the Media Migration project page on Drupal.org, because it is the only source that states what the module converts from Drupal 7 managed files and media items into Drupal Media entities and how stable it is. Read the alpha stability notice closely: the project has no supported stable release and warns that breaking changes can arrive between alpha releases. Note the exact release you plan to pin, read its issue queue for open problems that touch your file and media types, and confirm that the version you test against is the one you will deploy. Record that version in your migration plan so a later update does not silently change the mapping.
Next, read the Drupal.org upgrade documentation for upgrading from Drupal 6 or 7 to Drupal 8 and newer. It explains that Drupal 7 sites are migrated into a new site with the core Migrate, Migrate Drupal and Migrate Drupal UI modules or with Drush, not updated in place. Use it to confirm which entities are covered by the core path, to check that the Media Migration steps fit the order of your full migration, and to plan the theme rebuild, since themes cannot be migrated and must be recreated in the new site.
Finally, read the Drupal 7 end of life partner page if your cutover date is not yet fixed. It lists the certified vendors that provide extended security support for sites that cannot migrate yet. Ask any vendor what it covers, how long the coverage runs and whether it includes the file directories and public URLs you still serve, because the media migration will not finish while the old site stays in production. Use that answer to decide how much time the migration timeline can absorb.
How DeployOpen works on this
DeployOpen scopes Drupal 7 files and Media to Drupal Media migration in writing before any build starts, then works inside your own infrastructure. The work is planned around the alpha status of the Media Migration module, so every decision about mapping, testing and rollback is documented for your team.
How we scope
- Inventory managed files, Media entities, image styles and file storage paths on the Drupal 7 source site
- Map each Drupal 7 media bundle and file field to a target Media type on the new Drupal site
- Define how embedded media tokens in body text will be found, converted and checked
- Agree the written scope, deliverables and timeline with your team before work starts
How we build
- Run the Media Migration module on a staging copy, pinned to a tested release because it has no stable release
- Build custom migration steps for file paths, token rewrites and fields the module does not cover
- Test migrations repeatedly on copies of the source database and file directory
- Record each mapping decision, known gap and rollback step in the project documentation
How we hand over
- Deliver migration code as version-controlled custom modules with a runbook for the production cutover
- Provide reconciliation reports comparing file counts, Media entity counts and broken embed checks
- Document the Media types, field mappings and file storage layout your editors will use
- Walk your team through the rollback procedure and the verification steps before sign-off
How we support
- Confirm with your team who owns the Drupal 7 source site until cutover and how long it stays available
- Agree post-launch checks for broken media links and missing files with a retainer if you want ongoing help
- Plan updates to the migration code when the Media Migration module publishes new alpha releases
- Ask for written terms covering support scope, response expectations and retainer options before you commit
