Drupal to WordPress Migration Guide

A successful Drupal to WordPress migration takes a great deal of planning. Find out what to expect and how to avoid expensive mistakes.

If you are a media agency or site owner with an upcoming Drupal to WordPress migration, you will want to fully appreciate the task ahead of you. Carefull planning, attention to detail and reasonable expectations are essential. This guide will help you understand the scope of the project and your options for exporting content.
I will cover the topic in detail. In a rush? You might want to head straight to the following sections:

• Drupal to WordPress Migration plugins.
• An open source migration script that you can customise.
• Checklists for key areas of the migration process.

Alternatively, please request a quotation for my Drupal to WordPress migration service.

Table of contents

Background

1. Why are Drupal users migrating to WordPress?
2. What can go wrong during a Drupal to WordPress migration?
3. Common site migration mistakes

Drupal to WordPress migration planning

1. Before you start a CMS migration project
2. How long will a site migration take?
3. The three main components of a CMS migration
4. Migrating Drupal users to WordPress
5. Migrating Drupal views and blocks to WordPress
6. Drupal to WordPress Migration checklists

Content migration

1. Drupal to WordPress migration options
2. Automated migration vs. migration service
3. My Drupal to WordPress utilities
4. Drupal to WordPress Migration plugins
5. Database tools and CMS migration helper utilities
6. Site migration workflow

Pre-launch, go-live and follow-up

1. Content quality assurance
2. Post-migration troubleshooting
3. WordPress hosting for site migration projects
4. SEO for Drupal to WordPress migrations
5. Manual adjustments
6. Go-live and follow-up

Appendix

1. Updates to this page
2. Other tools, resources and guides for CMS migration projects
3. Download my Drupal to WordPress migration tools
4. Sample Drupal to WordPress migration checklists

Background

1. Why are Drupal users migrating to WordPress?

Many developers and site owners jumped on the Drupal bandwagon in the early 2000s. At that time it was the only real option for a content management system (CMS). Since then it has transformed into a platform more suited to enterprises, with a steep learning curve, demanding regular performance tuning and expensive hosting. Additionally, backward compatibility between versions has been a serious problem as major version upgrades essentially meant rebuilding the site from scratch. Rather than spend the resources needed to upgrade, site owners often choose to stay with aging, outdated sites that become prone to attacks. Those who decide to move from their current Drupal version often end up looking to migrate their sites to an different platform.
WordPress is an ideal alternative to Drupal for site maintainers with simpler requirements. It has a smaller footprint; user-friendly interface built-in; lower management overhead; and rich plugin ecosystem. There’s also no shortage of WordPress guides to help you on your way and if you need someone to do the work, there are many developers with reasonable rates.

2. What can go wrong during a Drupal to WordPress migration?

Many migration guides, tools and services make the process seem so simple. If you can migrate your site from Drupal to WordPress in a few easy steps, how much can really go wrong?
Here’s the best way to highlight the answer: run a web search with variants of the keywords site, migration and disaster. See how many results you get back.
From my experience, there are broadly two types of site migration failures: traffic drops and runaway costs. These failures have different results but the effect is the same. Everyone leaves regretting the entire endeavor.

Traffic drop

Traffic to the new site may plummet after migration. Usually this is due to failing to address the SEO impact of the changes. Sometimes it can be due to visitor dissatisfaction with the new design or overall user experience. The traffic drop may be permanent, destroying online revenue.

Runaway costs

The migration process itself ends up blowing away your budgetary estimates. Remember costs can mean both money and employee time. A seemingly cheap solution or improper planning could immerse multiple staff members in never-ending migration misery.

3. Common site migration mistakes

Site migration failures stem from the same root causes: inadequate planning and unrealistic expectations. This is why I will spend a lot of time talking about planning and understanding what’s involved.
Be sure to avoid these top ten common migration mistakes:

1. Poor planning (or not making any migration plans and contingency plans).
2. Underestimating the scale and scope of the migration project.
3. Bringing in key people too late into the project. (Do you need involvement from migration consultants; SEO consultants; developers; system administrators; testers; content editors; decision makers?)
4. Using inexperienced migrators or developers.
5. Rushing to launch. Is there a reason for picking that launch date? Is it realistic?
6. Allowing excessive scope creep. Try not to tackle too much all at once.
7. Failing to understand how the changes will impact your wider business. For example: How will traffic changes affect revenue projections? Will the user experience cause increased support requests? (Users include visitors, editors and maintainers.)
8. Poorly communicating what’s happening—and why it’s happening—to everyone who needs to know.
9. Not running pre and post-migration audits and benchmarks.
10. Inadequate testing. For example, will that combination of new custom theme and plugins cause a performance drop on the live server?

---

Drupal to WordPress migration planning

1. Before you start a CMS migration project

Drupal to WordPress migration projects are often complex and need to be handled carefully. Rather than jumping in head-first, take some time to plan your approach. Before starting the migration project itself, I highly recommend reading my guide, How to prepare for your Drupal to WordPress migration project. The migration checklists below will help make sure you’re considering areas that often come up during migration projects. Furthermore, you may want to check the resources section for additional worksheets and guides. Also keep in mind that not all aspects of a migration are practical to automate. In many cases, you may need to make manual adjustments post-migration using the WordPress interface.

Basic migration planning

At any rate, you should at least take some basic planning steps before you begin:

1. Consider why you are migrating to WordPress.
2. Decide on your approach to building the WordPress theme.
3. Be aware of any SEO impact when migrating to WordPress.
4. Gather as much information as you can about your Drupal installation.
5. Write a Drupal to WordPress migration mapping document.

Incidentally, it’s easy to overlook the fact that you don’t need to make an exact copy of your Drupal site in WordPress. Prioritise the highest value content and functionality if time and budget is tight. To that end, putting together migration requirements will help focus your efforts.

2. How long will a site migration take?

There are automated migration services that claim to do a great job in 15 minutes. In my opinion, this severely underestimates the scope of the work necessary and overlooks the importance of pre-migration planning and auditing, as well as post-migration quality assurance. One common remark I hear from people who have gone through the process is that it ended up being much more work and taking much longer than they expected. While automated tools and scripts will speed up transferring your content, be aware that manual adjustments will be necessary in almost every project. There is currently no way to automate the work performed by skilled content strategy experts, editors and quality assurance testers.

Hours and timelines for the average migration project

From experience with my own migration projects, I’ve found that a small site can take anywhere from 20-30 hours. The average content-focused site, such as a blog or news site, can take me between 50-100 hours to complete. Complex migrations for e-commerce sites can take 80-130 hours. Your experience will differ but it’s certainly much more than 15 minutes. In terms of time to launch, I always recommend leaving at least three months from project kick-off. Six months to one year for a large, business-critical site with lots of stakeholders requiring sign-off approval is not uncommon.

3. The three main components of a CMS migration

There are three main components of a site migration:

1. Site content
2. Design templates
3. Functionality

Web developers experienced in either Drupal or WordPress platforms will be familiar with these aspects of a site but I’ll give a brief overview for site owners and business-focused staff.

Site content

The content, such as the pages, articles, blog posts, and media uploads, make up the core material for your site. Content is separate from the design aspects like the textures, buttons and other bits of ‘eye-candy’ that go into making the site visually appealing. Content migration is nearly always the primary focus of any CMS migration project. Both Drupal and WordPress store content in a database that supports widely-used open source technologies. While they share the same basic technologies, Drupal uses a different database structure, or schema, which cannot be directly copied into a WordPress database. The technology’s open-source nature makes it feasible to export content from one system to the other but our challenge is in knowing the best way to translate those different storage structures.

Design templates

Design templates display your content with a specific look and feel. Under Drupal and WordPress, these design templates are called themes. When you first created your site, the main building effort would have been for a designer to come up with a look that you like and for the developer to translate that look into web code. The designer and developer may have been the same person but design and code are separate tasks. In my experience, site owners usually take the opportunity to update the site design during a migration. Some hire a designer to come up with a custom look but those on a budget tend to download a pre-made theme. Arguably, a big part of WordPress’ success lies in its wide range of professionally designed, easy to install, easy to use, and easy to customise theme selection.

Functionality

Under Drupal, site functionality comes in the form of modules. WordPress calls these plugins. Both modules and plugins are additional software components that extend the core content management system’s utility. The vast majority are created by independent developers and web development shops. Modules and plugins help create feature-rich websites quickly and at a lower cost than programming from scratch but they have an important downside: site owners can face a serious problem if the original developer abandons their efforts. I have found many long-running Drupal sites to be cluttered with out-dated and abandoned plugins. In fact, the push to migrate often stems from concerns about dependencies and the inability to upgrade without breaking the entire site, mostly due to a critical but abandoned module. Just as WordPress offers a wide range of themes, it also offers a rich ecosystem of plugins and plugin developers. Site owners can replicate legacy Drupal functionality by building a custom WordPress plugin or by installing one of the many free or premium offerings.

4. Migrating Drupal users to WordPress

Unsurprisingly, migrating user accounts is a high priority for owners of membership and community sites. Whereas most areas of a site migration can be run behind-the-scenes, it’s important to know that user account migration will need action from people with login access. This might present you with an extra user management challenge after the migration. First, here’s an overview of the user components that need to be mapped in the database:

• User data and metadata: This includes elements such as the user ID, username, email address and associated profile fields. In most cases, Drupal user fields can be mapped fairly easily into the WordPress user and usermeta tables.
• Roles and permissions: Drupal’s roles and permissions are more flexible when compared to WordPress roles. Nevertheless, it’s possible to shoehorn a Drupal site’s access control model into standard WordPress roles with a bit of creativity. WordPress has many access control and user management plugins if you need to set up more complex login permissions.
• Content authorship: Assigning post authorship is straightforward by setting the posts’ post_author field with the appropriate user ID.
• Credentials: Due to the different password hashing algorithms used by Drupal and WordPress, the user password cannot be easily migrated.

Password hashing and why it matters for your migration

To understand why you can’t easily transfer the password field when migrating Drupal users to WordPress, you need to know about password hashing. Hashing is a method of irreversibly scrambling text: password text is converted using a mathematical operation into a set of alternative characters (the ‘hash’) but you can’t use that operation to convert those characters back to the original password. It’s a one-way process that’s as strong as the mathematical operation, or the hashing algorithm. Some methods make reversing the process more difficult by adding a ‘salt’, which is an additional random bit of text. The hash and salt technique is often used to secure passwords in the event of a data breach. Drupal 7 and Drupal 8 use a hashing algorithm called SHA-512 with a salt while Drupal 6 uses MD5 without a salt. WordPress, on the other hand, uses MD5 with a salt. The different hashing mechanisms means that as far as WordPress is concerned, any text migrated into the password field is unusable. It has no way to get back to the original password. When a users tries to log in, it can’t tell if the entered password is correct.

Plan your post-migration password reset process

The consequence is that there’s no simple way to seamlessly migrate user passwords. I mean this in the ethical ‘white-hat’ sense. Malicious hackers can use other techniques to crack the password but these aren’t viable for a migration project. If it were, we’d be presented with a security failure as anyone with access to the database could reconstruct user passwords without too much effort. After the migration, your users will therefore need to reset their passwords on the new WordPress platform before they can log in. If you have many users on the legacy Drupal site, it’s worth considering how to manage this process during your migration planning stage.

5. Migrating Drupal views and blocks to WordPress

Drupal views and blocks are among the most powerful and regularly used features available to Drupal developers. They help web builders create data-rich displays by showing content listings on different areas of the site. Note, however, that views and blocks aren’t bits of content themselves but a method of presenting content in different ways. Nevertheless, they’re sometimes important considerations during a site migration because of their close relationship to how visitors experience the site. It’s worth taking a bit of time explaining what views and blocks are and how to transfer them to WordPress.

Migrating Drupal views to WordPress

Views are simply groups of content organized into listings. For example, you can have a view that lists recent comments, top articles by month, posts from users, or terms in a particular vocabulary. They’re controlled by the Drupal Views module which allows site builders to query the database without writing code. Essentially, Drupal Views is a point-and-click wrapper for some powerful database queries that pull out and sort content. WordPress developers usually build these types of content listings by querying the database in code using the WP_Query programming interface. There have been WordPress plugins, such as Query Wrangler and Query Posts, offering similar functionality to Drupal views. Unfortunately, these now seem to be abandoned projects. Toolset, a plugin mentioned in the Drupal to WordPress Migration plugins section below, offers a views query builder for WordPress but you’ll have to pay a yearly licence fee. I prefer to ‘migrate’ a Drupal view into WordPress by coding it into a child theme template. The WP_Query interface is a standard theme developer tool so a lighter-weight approach makes more sense to me. Installing plugins to handle views functionality may lead to unwanted dependencies and licence renewal costs in the future. On the other hand, any experienced theme developer can adjust theme templates without too much trouble when needed.

Migrating Drupal blocks to WordPress

Drupal blocks are boxes of content that can be placed on different areas of a page. Drupal views are usually displayed in blocks so the two features tend to work together. WordPress has a direct equivalent for blocks: Widgets. As with views, blocks fall into the theme and development domain but people often ask about migrating Drupal blocks into WordPress. They are best considered part of the theme or plugin development effort rather than the content migration phase.

6. Drupal to WordPress Migration checklists

Migrating websites to a different content management system is notoriously complex but even seasoned developers still underestimate the amount of work involved. Drupal to WordPress migrations can be especially tricky because they target very different types of users. Consequently, their platform architectures are also very different. You can quickly run into trouble if you forget some key areas during your migration process. My own migration project framework starts off with an analysis phase designed to discover as much as possible about the client’s needs and the project’s impact on project resources. Over the years I’ve compiled a set of questions and considerations specifically for Drupal to WordPress migrations. They’re organised as checklists of three main areas that often concern my clients:

• Understanding their migration requirements
• Auditing the existing Drupal site
• Addressing any SEO impact of the migration

I regularly update them to include new items that often come up and you can find them in the Appendix section of this guide. A web search will also bring up many detailed migration checklists targetted to website migration SEO. Whether you use a pre-defined checklist or compile your own from scratch, I strongly recommend that your migration project be based around some sort of checklist framework. No matter how many CMS migration projects you’ve completed, it’s easy to forget important tasks without them. View my sample Drupal to WordPress migration checklists.

---

Content migration

1. Drupal to WordPress migration options

I’ve been migrating sites from Drupal to WordPress since around 2011 and conclude that there’s no single method suitable for everyone. Generally speaking, you have the following options.

Migrate manually

If you have a small site and some time on your hands, you can simply copy-and-paste all your content across. It’s an incredibly boring task but sometimes a low-tech solution is what’s needed. I’ve even been contacted by operators of large sites with tens of thousands of posts who have considered this option. They usually plan to off-shore the work to a cheap labour location so the price is bearable. In my opinion, manual migration is unwise for large sites since quality control would be a nightmare.

Install a plugin or automated migration software

Several companies offer software that try to migrate content. CMS2CMS and FG Drupal to WordPress appear to be the main choices at the time of writing. CMS2CMS charges a fee calculated from the amount of content you want to migrate. FG Drupal to WordPress, on the other hand, follows a ‘freemium’ model. I’ve personally not needed to use this kind of migration software so I’m unable to comment on how well they perform. I can, however, offer an assessment of their merits based on available documentation and user feedback.

Customise an open-source migration script

The tools I offer fall into this category. Furthermore, there are plenty of scripts and tutorials detailing how you can go about exporting Drupal content into WordPress. Still, you should carefully consider if the time investment and effort needed is worth any monetary savings. Developers who come to me with a migration project often comment on how they under-estimated the amount of work needed.

Hire a content migration consultant

Since I offer a Drupal to WordPress migration service, it goes without saying that I’d recommend this route as the one giving the best results. Admittedly, budget is always a factor so hiring an expert may consequently be unrealistic for some situations. Nonetheless, those with heavily customised content types, complex taxonomies or specialised modules may have no other choice. An expert will also help steer you away from pitfalls that could end up being very expensive to fix.

2. Automated migration vs. migration service

You have probably found several Drupal to WordPress migration plugins and automated tools while researching this topic. Perhaps you’ve found services, including my own, offering a custom migration service. So, what are the advantages and disadvantages of either route? The answer depends on the complexity of your configuration and the particular goals of your migration.

When to use a migration plugin

Generally, migration plugins can convert Drupal content that have a clearly defined counterpart within WordPress. For example, export for article titles, the main article content body, tags, categories, and comments can be easily automated. A migration plugin may work for you if:

• Your Drupal installation has very little in the way of customisation, such as a simple page-and-article setup, or uncomplicated custom content types.
• The Drupal modules installed are fairly mainstream and can easily export into a WordPress equivalent plugin.
• You run a hobby site with very little budget or are willing to spend time figuring things out.

When to hire a migration consultant

On the other hand, automation does fall short in some important ways. A great deal of the most valuable content in your Drupal site is often configured in ways that need human decisions. For example:

• Which migration approach should be taken?
• How closely will the approach meet your project’s goals?
• Will one WordPress plugin or another better suit your workflow?
• What kind of compromises must you make?
• How will you handle custom content types?
• Will Drupal taxonomies be handled differently within WordPress?
• Are you combining or converting content types?
• Is data cleaning required and will you do that during migration or after going live?

These are critical decisions that cannot be automated. Human experience often provides more value than the short-term savings of a migration plugin. As a result, a reliable custom migration service does cost more than an off-the-shelf plugin but in return, you avoid expensive and potentially long-term problems. Additionally, if you’ve read the first few sections of this guide, you may have realised that site migrations often involve more than simply migrating the content. If your website plays an important role in your business or outreach activity, it’s probably a good idea to get an expert to advise you.

3. My Drupal to WordPress migration utilities

In the early days of Another Cup of Coffee, I specialized in setting up and configuring Drupal since it was—and still is—a versatile content management system. However, starting around 2011, new and existing clients began asking me to convert their Drupal sites to WordPress. Manually exporting content from Drupal to WordPress would have been too time-consuming, especially for sites with lots of content types and entries. I therefore decided to hack together some scripts to build my own conversion tool. The first web-based version of my Drupal to WordPress Migration Tool was released in 2013 and then later replaced by a Python-based command-line tool. The software has been released under The MIT License so feel free to customize the code to suit your own migration project. Download my migration tool and read the instructions in the Appendix section below. It was designed for complex migrations using my own workflow so you will need some coding knowledge to get started.

4. Drupal to WordPress Migration plugins

I offer a competing service so no doubt you’ll take this section with a grain of salt. Nevertheless, I will try to be as objective as possible. At the time of writing, there seem to be two Drupal to WordPress Migration plugins on the market, FG Drupal to WordPress and CMS2CMS. Of the two, FG Drupal to WordPress is the only plugin that does not require a paid service but its free version is limited. Another plugin, Toolset, deserves a special mention because while it doesn’t handle content migration, its tutorial comes up when searching for the topic.

FG Drupal to WordPress plugin

The FG Drupal to WordPress plugin operates on a ‘freemium’ model. Its free version migrates standard content like Drupal pages, articles, images and taxonomies. You will need to pay for the premium version for a more extensive migration of comments, users, custom content types, custom fields and custom taxonomies. Purchased add-ons are necessary to support features like CCK custom fields, meta tags, and Drupal field collections.

Favourable reviews

It does have an obvious advantage over CMS2CMS: people on the WordPress Plugin Directory give FG Drupal to WordPress good feedback, on average rating it 4.6 out of 5 stars. Users also comment on the helpfulness of its author, Frédéric Gilles.

Creating dependencies

However, there is one big downside to be aware of when considering FG Drupal to WordPress. The plugin creates some dependencies on your migrated WordPress installation, even after the site migration:

• FG Drupal to WordPress itself needs to stay activated for the life of your WordPress site in order to manage redirections and user authentication.
• If you use custom content types, you will need the Post Type Switcher plugin to create the content types.
• The Taxonomy Switcher plugin is needed to convert custom taxonomies into WordPress categories.
• You will need the Toolset Types plugin, also for the lifetime of your WordPress installation, to support custom post types.

As any seasoned WordPress developer knows, plugin dependencies are a concern because important features of your site could stop working if the author abandons the plugin. To be fair, this goes for any plugin, not just for those that you use for site migrations.

Good for standard content

In summary, FG Drupal to WordPress seems to be good at doing its intended job of automated migration for standard content. Add-ons and extra plugins will be needed for anything more complex. I think this is a fair compromise because there are so many possible configurations that it’s un-realistic to expect one single plugin to cover all use-cases.

CMS2CMS plugin

CMS2CMS clearly aims at the wholesale end of the market, claiming on their website ‘80,000+ migrations performed’, an average 15 minutes for a full-scale CMS migration and no coding, with ‘a few mouse cliks’ to do the job. They are often mentioned in the comments section whenever there’s an article about migrating from Drupal to WordPress. Interestingly—and in contrast to FG Drupal to WordPress—actual user experience doesn’t seem very favourable; they only rate 3.2 out of 5 stars on the WordPress Plugin Directory.

Limited demo only

Personally, I suspect the poor reviews are more to do with their marketing and a case of over-promising. It turns out the CMS2CMS WordPress plugin only migrates 10 pages or posts. The details on the WordPress Plugin Directory do mention running a free demo migration but it’s not entirely clear that the plugin is severely limited. I cannot imagine this plugin being useful for anyone operating a mature real-world Drupal installation, even as a demo. You will need to sign up for their paid service if you’d like to run any kind of serious content migration. Fees are estimated based on the amount of content you enter on their CMS migration price calculator.

Satisfied paying clients

Judging by the testimonials on their site, there are clients very satisfied with their service. Nevertheless, their marketing approach is quite unfortunate because even if they do offer a good service, the tactics have obviously been poorly received in the plugin’s review page.

Toolset plugin

OnTheGoSystems’ Ultimate Guide to Migrating from Drupal to WordPress comes up when searching for the topic. The guide is based around their Toolset plugin so I thought it deserves a special mention. Toolset itself doesn’t actually handle any content export/import functionality. Instead it provides Drupal-like features, such as custom post types, blocks and views, within the WordPress platform. You will still need to find a separate solution for the content migration itself.

Not solving the content migration problem

Toolset suggests creating an export file using Drupal’s Backup and Migrate module, then installing a third-party import plugin and possibly some Toolset compatibility add-ons. Therefore, while the plugin gives you a way to ‘migrate’ Drupal functionality into WordPress, it doesn’t solve the content migration problem. It only offloads the job to another component, assuming that you’ll somehow get it sorted. The guide even suggests adding custom code or hiring a professional to get the job done right. Clearly, Toolset is a site-builder plugin and not a migration plugin.

Drupal-like functionality for WordPress

On the plus-side, the guide does a good job of explaining the WordPress equivalents of Drupal features. It also offers a comprehensive point-and-click method of developing Drupal-like behaviour in WordPress.

5. Database tools and CMS migration helper utilities

Content migrations involve spending a great deal of time manipulating the database. It’s therefore useful to have a set of tools to make things easier. Here are some third-party utilities that can help with your migration project:

• WP-CLI: A command-line interface for WordPress that I’ve found particularly useful during migration projects. For instance, you can use it for installing a new instance of WordPress, updating user credentials and activating plugins. WP-CLI will save you having to write SQL queries for simple database tasks that go along with a migration project.
• Database search and replace script: Sometimes you need a way to search and replace text in the database. This PHP-based tool is useful for environments without command-line access, such as those offered by cloud-based hosting providers.
• Search & Replace WordPress plugin: Though I haven’t personally used this plugin, quite a few developers seem to recommend it.
• Drupal to WordPress Image Migration plugin: Brendan Carr’s WordPress plugin to help migrate images from Drupal 6.
• Drush: A Drupal command-line shell which can be used, for example, in migrating Drupal sites. In particular, you can use it create a development version for analysis prior to exporting to WordPress. As a matter of fact, there’s a drush bam-backup command to backup a site’s database with the Backup and Migrate module.

6. Site migration workflow

Web development projects tend to use a variation of the Build/Test/Deploy workflow. If you’re operating within a media agency or development shop especially, it should come as no surprise that site migrations can follow a similar process. For Drupal to WordPress migrations, I recommend the workflow:

Migrate

The Migrate stage covers content export, redesign, theme development and feature porting. Separate teams can work on the different elements within their own environments. When the content export team and development team are working concurrently, they should work within their own isolated environments. This is because WordPress stores lots of its theme configuration within the database. If the content export team writes to the development team’s database without taking precautions, they risk overwriting the dev team’s work…and having a bunch of grumpy developers. You can greatly simplify a migration project by exporting the Drupal content into a blank WordPress database first, then working on theme and plugin development on top of that installation. This avoids having to do a complex database merge later on in the project. Nevertheless, project timescales often mean is isn’t viable for all migration projects.

Test

The Quality Assurance team can check the accuracy of the exported content separately from testing theme and plugin development. When testing the content export, the goal is to verify that all the required custom fields and metadata have been migrated from Drupal; that content hasn’t been corrupted; that all the expected content is present; and that the taxonomy relationships are intact. I like to start off with a bare-bones theme like Twenty Sixteen in the early stages of a migration because there’s no extra eye-candy to distract from the content.

Migrate and Test iterations

For my projects, the Migrate and Test stages are iterative. Drupal to WordPress migration projects are usually quite complex so it doesn’t make sense to try exporting all the content in one iteration. I usually focus on one part of the project first, like high priority content types. The QA team checks the exports and sends their feedback. If necessary, I’ll tweak my migration scripts and migrate again until QA gives the OK to move on to another area, like taxonomies. This process repeats as often as necessary to get the results specified.

Merge

You will need to merge databases if the content export team and development team have been working on separate environments. This is a complex topic and the details are often project-specific so I won’t elaborate here. Just understand that you will need to take care that database rows created by the Drupal migration don’t overwrite rows created by your development team.

Deploy

Fingers-crossed, you end up with a successful migration and it’s time to launch. Choose a good hosting company and deploy your new WordPress site.

---

Pre-launch, go-live and follow-up

1. Content quality assurance

Even if you decide to outsource the content migration work, you should still allocate resources within your in-house team to perform the quality assurance (QA) tests. Your own content editors, being most familiar with the site content, will be the best people to review and check the migrated data. External migration consultants will not have the same familiarity with the nuances of how your content ought to be structured. They will often miss obvious discrepancies that a content editor will spot at a glance. It can be tricky to adequately test sites with many thousands of posts. This is very much a manual process that needs a human to ‘eyeball’ the migrated content. The big problems, such as broken links and missing fields, may be immediately obvious. Other issues, like text encodings and foreign language character set discrepancies can take a while to surface. Expect to spend considerable time with back-and-forth communication between your migration team and QA team as they try to resolve issues. An iterative migration workflow will simplify the process but sometimes you may have to accept that certain problems need old-fashioned manual resolution. In other words, someone might just have to edit a bunch of specific posts to fix the problems over time, after the site has launched.

2. Post-migration troubleshooting

The complexity of many projects means that you may encounter problems with your WordPress installation after migrating content. There could be any number of reasons for these errors but checking my Drupal to WordPress migration notes might point you in the right direction. Alternatively, browse through my migration troubleshooting posts where I keep a record of problems that regularly arise. Here are a some common errors, along with a link to a possible solution.

• Incorrect domain in URLs: This is a very common error where you may have forgotten to replace the old domain or development URL with that of your live site.
• Clicking on author’s link gives 404: Invalid characters may have been migrated into the WordPress user_nicename field.
• Gateway timeout when enabling plugins: The WordPress upload path directory may be set incorrectly.
• WordPress redirects to old site after updating database: Sometimes a caching plugin redirects you to the old domain or development URL.
• Post migrated but navigating to post shows ‘Not found’ error: Usually an invalid character in the WordPress slug or .htaccess not enabled in the Apache configuration
• Dashboard controls not visible after logging in: table prefixes may not have been updated.

3. WordPress hosting for site migration projects

Search the web for WordPress hosting and you’ll find a ton of articles with reviews, recommendations and feature listings. Instead, I’ll focus on web hosts I’ve personally used specifically for Drupal to WordPress migration projects. WordPress runs on pretty much any standard hosting package on the market. A hosting company has to go out if its way not to support WordPress. You might even run your own servers in-house that are ready to host both the migration and production environments. Keep in mind that a good hosting environment streamlines the migration process by offering tools to make your life easier. Poor hosting will plague your project with connection timeouts, failed database imports and manual configuration of basic utilities.

Managed WordPress hosting

Of all the hosting packages I’ve used over the years, managed WordPress hosting services have given me the best migration experience. Managed WordPress hosting is certainly more expensive than regular hosting but there’s no need to stay on the package after going live. If your budget allows, you might the benefits worthwhile and decide to stay. In alphabetical order, I have used and will be happy to use again the following:

• Drupion
• Kinsta
• Liquid Web
• Pantheon
• WP Engine

Speaking from my own experience, all of these companies have responsive and helpful customer support. All offer the basic tools needed for Drupal to WordPress migrations involving remote teams such as secure remote access, WP-CLI, and database client. Pantheon is a little different from the others listed in that their environment enforces a Dev/Test/Live workflow that requires some documentation trawling. It took me a while to get used to Pantheon but I like their offering.

4. SEO for Drupal to WordPress migrations

Drupal to WordPress migrations follow the same SEO considerations as other types of migrations. I therefore won’t detail them in this guide as site migration SEO is an in-depth area. There are plenty of online articles from dedicated SEO specialists that will do a better job. Furthermore, if search traffic is important for your site, you will likely have been working on it throughout the project. You have thought about the SEO considerations, right? Too many clients come to me at the end of their site development efforts and optimistically ask that I:

1. Migrate their content, hopefully within a week;
2. and, oh yeah, ‘migrate the SEO’.

The pre-launch stage is too late to start thinking about SEO but if search traffic is important for your site, this is a reminder is for you not to leave it for post-launch. If you’d like to know more about some specifics of preserving SEO during a Drupal to WordPress migration,scroll down to the Appendix section for my guide for preserving SEO during a Drupal to WordPress migration.

5. Manual adjustments

Sometimes it’s impractical to automate every aspect of a migration. For example, some quick adjustments using the WordPress user interface just before launching may be simpler than writing code to script a task. The particular tasks themselves depend on your migration requirements but most projects have an element of manual fixing-up prior to going live. It’s important to leave time in the pre-launch schedule and identify a person, usually a technically-minded content editor or intern, to do the job. It can also be the case that you’ll need to do the adjustments after go-live as part of your long-term content curation process. For example, I once had a client whose authors manually embedded HTML advertisements in their content body. The code didn’t match a well-defined pattern so removing the adverts through a script or SQL query risked silently breaking HTML in some posts. The client decided it made more sense to fix these over time as they pruned their content. Be practical in your migration approach and keep in mind that a low-tech solution can be the answer to some problems.

6. Go-live and follow-up

Going-live isn’t usually the end of a migration project. As mentioned above, there may be some long-term adjustments and content cleaning needed. Remember also to allocate time and budget for any post-migration SEO analysis. Nevertheless, the bulk of the work will be done and you can enjoy the advantages of running WordPress. These may include:

• A more user-friendly interface for non-technical users.
• Lower development costs through plugins and more affordable developer rates.
• Lower hosting costs.
• Easier maintenance.

Gauge the project’s success by reviewing your goals for migrating to WordPress and follow up to see if those expectations were met.

---

Appendix

Updates to this page

Last updated on 17 October 2019. Major revisions:

• August 2018: Following on from making this a more general resource, I’ve renamed this page to Drupal to WordPress migration guide.
• February 2017: This page has been receiving lots of traffic over the years. I’ve therefore converted it to a general Drupal to WordPress migration resource in the hope that it provides more value to visitors.
• August 2015: It’s been some time since I’ve updated the web-based PHP Drupal to WordPress Migration Tool. After a number of Drupal to WordPress migrations, I find the PHP and HTML platform to be inefficient for complex Drupal configurations. pyD2W is my Python-based command line replacement better suited to complex set-ups. View the repository on GitHub.
• July 2015: Do you need to migrate images from Drupal to WordPress? Check out Brendan Carr’s Drupal to WordPress Image Migration plugin.
• 21 June 2014: Moved the The Drupal to WordPress Migration Tool repository to GitHub.
• 26 May 2013: First release of the The Drupal to WordPress Migration Tool: drupaltowordpress-d6w35-0.3.zip

Other tools, resources and guides for CMS migration projects

Drupal to WordPress migration worksheet

It’s important to gather as much information possible about your Drupal installation before starting the migration project. You can use my Drupal to WordPress migration worksheet to help structure your investigation process.

How to write a migration mapping document

Preparing a CMS migration mapping document before starting your project will save you time. It simplifies the project by giving everyone a clear idea about the type of content involved. This short overview will get you started with writing a migration mapping.

Preserving SEO during a Drupal to WordPress migration

Is SEO is important to the project? See my guide for preserving SEO during a Drupal to WordPress migration. I explain the differences between Drupal and WordPress URL structures and pitfalls to keep in mind. Read it on the blog section: Preserving SEO during a Drupal to WordPress migration.

Troubleshooting Drupal to WordPress migrations

If you’re running your own Drupal to WordPress migration project and encounter problems, you might find some solutions in my migration troubleshooting articles.

Scott Anderson’s blog post

Much credit goes to Scott Anderson and his blog post, How I migrated a client’s blog from Drupal to WordPress 3.0. His set of MySQL queries were invaluable when I started migrating client sites from Drupal back in 2011. Scott cites Mike Smullin, D’Arcy Norman and Dave Dash as sources.

A Guide for Drupal Developers Migrating to WordPress

This guide from OnTheGoSystems gives Drupal developers an introduction to the WordPress interface. While it doesn’t go through running a content export, it’ll help if you want a quick introduction to using WordPress.

WordPress Codex

The WordPress Codex has a page on importing content form different sources, including Drupal.

Content migration tools for other platforms

Looking to migrate other types of content? Visit my migration tools page for utilities to migrate content from other platforms.

Download my Drupal to WordPress migration tools

CAUTION: Make a backup of both your Drupal and WordPress databases before running these scripts. USE IS ENTIRELY AT YOUR OWN RISK. I’m offering them with no warranty or support implied.

Download Drupal to WordPress Migration Tools

Description	Platform	Download
pyD2W, a command line Drupal to WordPress Migration Tool	Python	GitHub
Web-based Drupal to WordPress Migration Tool	PHP & web front-end	GitHub
Sample SQL queries for migrating content	MySQL	GitHub

Important reminder

These scripts and tools run MySQL queries to read information from a Drupal database and convert the content to WordPress. They may write temporary tables and make changes to your Drupal content. With this in mind, it’s imporant to avoid working on your live Drupal database. Above all, make backups before using these tools.

Web-based Drupal to WordPress export utility

This web-based utility, released in 2013, was my first attempt at building a Drupal to WordPress migration tool. It was based on my in-house scripts to migrate standard content types from Drupal 6 to WordPress 3.5. Although functionality is rudimentary and the tool is no longer being maintained, it might be useful for simple sites if you have a technical disposition. The code uses PHP 4 so you’ll need to make changes to run on modern environments.

Feature list:

• Migrates content from Drupal 6 to WordPress 3 and 4 database
• Shows number of Drupal terms, node types and entries to be migrated
• Select Drupal content types to be converted into WordPress posts
• WordPress file directory setting
• WordPress permalink structure setting
• Select which Drupal terms will be used as WordPress categories
• Select the WordPress default category

Web-based content migration: Installation and use

1. Copy the package folder to a web server.
2. Edit the MySQL queries. (See below.)
3. Run the drupaltowordpress.php script on your browser and follow the on-screen instructions to export content.

Both the Drupal and WordPress databases should be on the same server and share the same connection details.

Editing the MySQL queries

While the web front end works with very basic Drupal installations, anything more complicated will need custom SQL queries. These can found in the drupaltowordpress-custom.sql file. The script contains sample values so don’t run it without understanding what will be performed at each step. You’ll need to edit the SQL queries to suit your own Drupal setup. For more information, see the SQL queries section below. For post-export troubleshooting, please see Drupal to WordPress migration notes for additional help.

Command-line Drupal to WordPress migration tool

I wrote a Python-based command-line tool because the web-based export utility proved too inefficient for complex Drupal configurations. Although it requires more manual editing of MySQL queries, you can more conveniently run heavily customised site migrations.

Command-line content migration: Installation and use

1. You will need to install the Python modules in the requirements section below.
2. Rename the settings-template.py to settings.py and edit it to match your migration project settings.
3. Edit the included SQL sample files in the sql-sample directory to suit your migration requirements. At a minimum, you will need the migration script itself (see the sample migration_standard.sql file).
4. Run the utility using the help flag to view the available commands: $ python d2w.py -h

Customising the export script for your Drupal setup

The Python script itself won’t perform the migration. To emphasise, you must supply it with an export SQL file containing the migration queries. See the SQL queries section for more information.

Required Python modules

• MySQLdb for accessing the backend Drupal and WordPress databases
• prettytable for displaying results in a table format
• phpserialize for unserializing Drupal fields

Note: all my latest versions of the command-line tool now include a requirements.txt file which you can use with a pip install -r command.

Drupal to WordPress Migration SQL queries

Both the web-based and command-line utilities are simply convenient wrappers for SQL queries. While you can run a migration by typing out individual queries in a database client, this will prove to be very tedious for all but the simplest of configurations. In fact, I built these tools precisely because manually entering SQL queries, line-by-line, quickly became unworkable. It’s important to realize that these queries are the engine of the migration. Consequently, understanding your Drupal database and composing the right SQL queries are key to a successful migration. Because the interface wrappers are useless without the queries, I’ve included a sample set in both packages. For information about customising the export script to suit your Drupal setup, see my step-by-step explanation of the Drupal to WordPress migration SQL queries. In general, you will need queries to migrate following:

1. Vocabularies and taxonomies
2. Drupal nodes to WordPress posts
3. Users
4. Comments and comment authors

You may additionally need to include queries to clear out unwanted content, merge terms, or export custom fields.

Sample Drupal to WordPress migration checklists

I use these checklists for my own Drupal to WordPress migration projects. Feel free to use them as templates for your own site migration. Please note I update them from time-to-time to include new items that regularly come up.