Site Building

Preparing for a Migration to Drupal for Drupal 8, 9, and 10

Planning for a migration is essential. In our collective experience we've never once seen someone sit down and execute a migration flawlessly on their first attempt. Migrations involve preparing and analyzing your source data, building a new website that data can be migrated into, and lots of testing, rolling back, and testing again, in order to get everything right. By the end of this tutorial you should be ready to start planning for your own Drupal migration project, and have a better understanding of the challenges of migrating from one system to another.


Begin preparing a migration plan.


This tutorial differs from most tutorials on our site where we give you a specific set of steps to follow to accomplish the desired outcome. We're going to pose a bunch of questions, and give you some things to consider when planning your migration, but for the most part we can't actually tell you the answer to the questions. That's your job.

What's more, no two migrations will ever be the same. There are simply too many possible variations, and a human factor, that makes the likelihood of ever having a single solution for all possible cases unrealistic. However, that means you're going to learn a ton about Drupal along the way!

A successful migration starts with a lot of careful planning and consideration of all the little details.

Why are you doing this?

Taking on a data migration is a big deal. Even for relatively small sites, it can be a time-consuming and challenging project. The benefit is that you've now got a shiny new Drupal-powered website. But it's important to take the time to understand your motivations, and the benefits that you hope to gain by moving your site to a new home. Even if you already know that the shiny new Drupal features are super cool, you might have some convincing to do when it's time to sell the project to others.

Your existing site already works. And it's not like it's just going to suddenly stop working. So what benefits do you hope to gain by investing time and resources into migrating to a new platform?

Consider your content

Prior to performing a migration you might want to consider doing a content audit. There's no sense spending a bunch of development cycles planning, crafting, testing, and debugging a migration path for content that you don't actually plan to make use of.

In our experience, the two most common things that come up when doing this are:

  • Identifying content that is no longer relevant and doesn't need to be migrated
  • Refactoring existing information architecture and chunking large fields of text into more semantic data suitable for use as an API or in other non-HTML contexts

For more information about content considerations when migrating from one Drupal site to another, see the "Consider your content and content types" section of the Preparing for a Drupal-to-Drupal Migration tutorial.

Do you really need that feature?

Before migrating any data, consider the platform. Unlike an OS upgrade where you hit "upgrade", come back in a few hours, and everything just works, a move to the latest version of Drupal is likely to be as much a rebuild as it is a migration. Without creating the application in the target version of Drupal first you'll have nowhere to migrate your content to.

What functionality is required, what can be removed, and what new features are you looking to add? A lot of times when you set out to perform a migration, you're moving from one application to another and need to account for the functionality in the previous application that your clients, and stakeholders, have come to expect. But at the same time, if no one is using the "gift certificates" feature of your site, for example, is it really worth the effort to rebuild it and migrate all the data?

Ask yourself, and your stakeholders:

  • What features of my site are people really using?
  • What features are not being used and can be left behind?
  • What critical new features will I be able to add as a result of migrating to a new platform?

Is it time for a facelift?

This is a great opportunity to give your website a facelift. That might mean simply tweaking a few design elements that you've been meaning to address for a while, finally implementing a responsive layout system, or a complete refresh of the design. When you migrate from any system (including prior versions of Drupal) to the latest version of Drupal you're going to end up needing to create a new theme for your site. This is true even if you're building a site without a migration component. Themes are the one thing that is custom for almost every Drupal project.

Creating a new theme by adapting existing design components will almost always be more efficient, simply due to the fact that you've already got some of the CSS and JavaScript written, and you've already done the hard work to figure out where and when to implement certain styles. That said, if you're pondering a design refresh shortly, you might want to consider doing it now since you'll already be spending considerable resources creating your custom theme.

Want to learn more about creating a custom theme in Drupal? Check out our amazing Drupal theming guide.

What's this all going to cost me?

Whether you're moving from a previous version of Drupal, or another data source entirely, it's important to frame this migration as a rebuild and not simply an upgrade. Doing so paints a more accurate picture of the amount of time and money this is going to take.

A migration is much more than just moving data from one place to another. The source data needs to be cleaned and prepared, the new website where data will end up needs to be created, designs updated, the new site needs to have a theme developed, infrastructure will need updating, tests will need to be written, and more. When assessing the cost of a migration we like to treat it as two projects: (1) Create the new site, and (2) Automate the transfer of content from the old site into the new one.

A successful migration will require at least a subset of the following roles among you and/or your team:

  • Someone who can do a content audit. A domain specialist who understands the idiosyncrasies of both your site's functionality and your content
  • A strong understanding of Drupal site-building and best practices
  • Drupal back-end developer
  • Drupal front-end developer
  • Systems Administrator / DevOps
  • Designer
  • Copywriter
  • QA

Other things to remember:

  • Drupal 8 (and continuing in Drupal 9) introduced major API changes to Drupal's system. Your site building, front- and back-end developers will need to be comfortable working with Drupal's current APIs (many of which were introduced in Drupal 8).
  • Your infrastructure needs will likely change with Drupal 9 (and 10)
  • Staff may need to be retrained how to use the site
  • Any new Drupal site, even if you're "just upgrading", is first and foremost a new website and should be handled as such
  • Upgrading from Drupal 8+ will be a much less arduous undertaking than Drupal 6 or 7 to the latest version of Drupal. See Upgrade to Drupal 9.

One thing to consider might be whether or not it's worth it to develop a custom migration path. If you've got a limited amount of data, the cost to develop a migration path may be higher than the cost to pay someone to copy/paste content between the old site and the new Drupal 9 one.


For Drupal-to-Drupal migrations I believe that this will be less of an issue as a large part of the work in developing migrations and field mappings is handled automatically. But, it's still worth considering.

Acceptance testing

What does a successful migration look like, and how are you going to assure yourself and your team that things are complete and ready to be shared with the public? If you've got more then a few hundred pages or so on your site it's unrealistic to expect someone to go through every single page and confirm that it migrated correctly. But you should test a large enough subset of them that you're confident things are working.

We recommend creating a list of key features of your site -- maybe pulling a list of your top pages from Google Analytics, and generating a baseline list of functionality that you'll want to test. This can also serve as a benchmark during the development process. How many of these requirements have you met currently?


In this tutorial we covered topics that you should be thinking about prior to starting any actual migration. Making sure that you consider these things ahead of time will help to ensure a successful project.

Further your understanding

  • Before you can ask stakeholders about migration planning and site features, you need to know who your stakeholders are. Make a list of the project stakeholders, thinking carefully about who any "hidden stakeholders" might be.

Additional resources