Drupal to WordPress Migration Guide

If you’re considering a Drupal to WordPress migration, these resources will help you export your content. Although I feature my own tools here, much of the information presented will be useful regardless of the method you choose.

Site migration graphic

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.

This page started off as the project homepage for my Drupal to WordPress Migration Tool. It has now evolved into a general resource for anyone who would like to migrate from Drupal to WordPress. If you are a media agency or site owner with an upcoming Drupal to WordPress migration, these resources will help you export your content.

1. Before you start a 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 continuing, I highly recommend reading my guide, How to prepare for your Drupal to WordPress migration project. 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.

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. The three main components of a Drupal to WordPress migration

There are three main components of a site migration:

  1. Site content
  2. Design templates
  3. Functionality

Web developers experienced in either CMS 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 makes up the core material for your site, such as the pages, articles, blog posts, and media uploads. Content is separate from the design aspects like the textures, buttons and other bits of ‘eye-candy’ that go into making the sit 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.

3. 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 can:

  • 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 an important 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.

4. Automated migration vs. migration service

You have probably found several Drupal to WordPress migration plugins and automated services while researching this topic. You may also have found services, including my own, offering manual migration. You may be wondering about the advantages and disadvantages of either route. This is a complex area and the answer depends on the particular goals of your migration.

Generally, migration plugins can convert Drupal content that have a clearly defined counterpart within WordPress. Export for article titles, the main article content body, tags, categories, and comments can be easily automated. Automation does fall short in some important ways, however. A great deal of the most valuable content in your Drupal site is routinely configured in ways that need human decisions. 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? These are critical decisions that cannot be automated.

A migration plugin may work for you if:

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

On the other hand, if the website plays an important role in your activity, human experience provides more value than the short-term savings of a migration plugin. A reliable custom migration service does cost more than an off-the-shelf plugin but it in return, you avoid expensive and potentially long-term problems.

5. My migration utilities

Skip this section

A quick plug for my Drupal to WordPress migration service

I give away lots of information for free so here’s a quick plug to keep the lights running. Site migrations are often very time consuming. You can save yourself considerable effort by hiring me to do the job.

Drupal to WordPress migration service

Any Drupal version · All content · Custom content types · SEO · Plugins

If you’re not sure how to make the appropriate changes or would simply like someone else to do the work, please contact me and ask about my Drupal to WordPress migration service.

Get a quote

Of course, if you’d rather try exporting content yourself, feel free to try my utilities below.

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

Note: As of 2018, this utility is obsolete for most people’s needs. I’m keeping it here since it contains sample SQL queries for Drupal 6 sites that some may find useful.

Skip this section

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:

Screenshot of our Drupal to WordPress migration tool

  • 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.

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.

6. 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.

FG Drupal to WordPress

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.

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.

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.

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

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.

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.

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.

7. Database tools and 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.

8. Post-migration troubleshooting

You may encounter problems with your WordPress installation due to the complexity of many migration projects. For example, WordPress might display permissions errors when trying to log in. Furthermore, content that seems to have been migrated may show a ‘Not found’ error. There could be any number of reasons for these problems. Checking my Drupal to WordPress migration notes might point you in the right direction.

9. Drupal to WordPress 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 → Test → Merge → Deploy

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.

10. 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.

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:

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.

11. Other tools, resources and guides

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 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 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.

Other migration tools

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


Appendix

A. Updates to this page

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

B. Download my migration tools

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

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.

Acknowledgements: