Documentation Level: 
Introduction
Documentation Status: 
No known problems

A full upgrade path from Drupal 7 to Backdrop 1.x is included for core modules.

Backdrop CMS acts as though it were the next version of Drupal for the purposes of upgrading, making it so that you can upgrade to Backdrop CMS directly from a Drupal 7 database.

Step 1: Research what will be necessary to upgrade to Backdrop CMS:

  • Review the theme in use on your Drupal site. Most Drupal sites use custom themes, that were built specifically for each site. Are you prepared to create a new theme for Backdrop CMS, port your existing one, or install a comparable alternative from contrib?
  • Review the layouts in use on your current site. Most modern websites use more than one page layout. Will you be able to make do with what's provided in core? If not, are you prepared to create your own layouts for Backdrop CMS, port your existing panels or Omega layouts, or install comparable alternatives from contrib?
  • Review the contributed modules in use on your current site. Very few Drupal sites run on what's in core alone. Have the modules you are using been ported to Backdrop already? If not, are you prepared to port them yourself? Most modules can be ported to Backdrop in a matter of hours; although a particularly complex module could take days.
  • Review the core modules and major features in use on your site. Does your site depend on anything that Backdrop has removed from core? If so, are you prepared to remove that feature from your site, or install a comparable module from contrib?
    • Modules & major features removed from core include:

Step 2: Prepare your Drupal site for upgrade

  1. Make sure your Drupal website is running the latest release of Drupal 7.
  2. Make sure you are running the latest stable versions of all your contrib modules and themes.
  3. Make a backup of everything: Backup the database, backup the files directory, and backup the codebase.
  4. Disable and uninstall core modules that have been removed from Backdrop CMS that you no longer need (see list above).
    • Note: uninstalling modules (Blog, Forum, Poll) may result in loss of content (or, more accurately, content that doesn't know what type it is). Please either delete content of these types before you uninstall the modules (if you no longer need it), or convert the content to a custom type.
    • PHP filter: Please clean up your PHP content before uninstalling this module. Once the PHP filter is removed, any content using it will fall-back to the plain text filter, printing your PHP code as though it were plain text. This could potentially expose private information to the general public, and may present a security risk.
  5. Save your Views (and other exported configuration) back into the database.
    • If you had custom views that were stored in code (either as Features, or simply exported views) you can manually edit and save each view to put its data back into the database. The Backdrop upgrade will convert these views for you, but only if they are in the database to begin with.
    • Note: If you were using the Features module in Drupal 7, you might try using the Unfeaturize module, to get your content types and fields back into the database. 
  6. Have a Backdrop version of your themes (and matching layouts) ready, or switch your theme(s) back to a core theme (we recommend Bartik).
    • Enable the core Bartik theme, and set it to default.
    • Change your administration theme to Seven.
  7. If you are running an install profile other than the core 'standard' profile, make sure you have a Backdrop version of that profile, or switch to the standard profile in Drupal 7. (Common examples are the 'pantheon' profile or the 'acquia_drupal` profile, if you are hosted on either of those platforms)
  8. Put your site into maintenance mode.
  9. Make a second backup of your database (this is the one you will use for Backdrop) we recommend calling it backdrop-ready.sql

Step 3: Upgrade your Drupal site to Backdrop CMS

We recommend setting up a second site, so that the Drupal version and the Backdrop version can be compared side-by-side. The instructions below follow that process.

  1. Start by following steps 1 & 2 from the Installing Backdrop page.
  2. Copy the files directory from Drupal into your Backdrop codebase. There are two possible ways to handle this:
    • Recommended: Move the files from where Drupal likes them, to where Backdrop likes them
      1. Copy the files directory from Drupal 7 (usually `drupal/sites/default/files`) into the Backdrop site (usually `backdrop/files`)
      2. Create a `default` directory within `backdrop/sites`.
      3. Create a symlink in your filesystem from `sites/default/files` to  `files` .
      4. After the upgrade, update the `Public file system path` setting at admin/config/media/file-system to `files`.
    • Alternative: Place the files in the same location they were in Drupal
      1. Create a `default` directory within `backdrop/sites`.
      2. Copy the files directory from Drupal 7 (usually `drupal/sites/default/files`) into the Backdrop site (`backdrop/sites/default/files`)
  3. Import the Drupal 7 database backup (backdrop-ready.sql) into the database you created in step 1.
  4. Update the Backdrop settings.php file according to step 3 from the Installing Backdrop page, to connect the Backdrop site to the Drupal database.
  5. Download all contributed modules, themes, and layouts for your Backdrop site, and place them in the appropriate directories.
    • Note: all modules, themes, and layouts must be in place before running the update, or crucial updates may be missed.
  6. Update your custom Drupal modules, and place the Backdrop versions in the modules directory for your backdrop site.
    • Note: At least 80% of the code in your custom Drupal modules should be compatible with Backdrop CMS. Major API differences include the configuration management system, and the Layouts system. Most other changes are minor.
  7. Open up a browser, and visit https://example.com/update.php to proceed with the update. (Replace example.com here with your domain or local site alias)
    • Note: You will need to be both logged in, and have sufficient privileges to run the update. If this is not the case, you can change $settings['update_free_access'] = TRUE;  in your settings.php file.
    • Note: Your site will not function normally, until after the update has been run; we recommend you run the update script before visiting any other page on your site.
  8. There will be over one hundred pending updates, but don't worry; in most cases, it will only take a few seconds to complete.
  9. Once done, click around your Backdrop site to confirm everything is working as expected.

Step 4: Test everything

Congratulations, your old Drupal 7 site is now shiny and new, and running on Backdrop CMS! In order to return your site to its previous working condition, however, there are just a few more steps.

  1. Enable a theme of your choice.
    • If you had a custom theme in Drupal 7, this will need to be ported, or rebuilt for Backdrop CMS.
    • If you were using a contrib theme for Drupal 7, this will need to be downloaded, ported, or rebuilt for Backdrop CMS.
      • Note: Theme's don't usually have updates of their own, but it's important that the Backdrop version theme be present during the update, just in case it does.
  2. Check blocks & layouts.
    • Double-check block positioning. During the upgrade, Backdrop will attempt to match the positioning from your Drupal 7 theme, to the Backdrop layouts.
      • Note: for this reason, it will be helpful to keep the Backdrop layout region names the same as the Drupal 7 theme regions.
    • If you were using a layout solution other than Blocks for Drupal 7, your old layouts may need to be rebuilt for Backdrop CMS.
  3. Check views.
    • Double check your views. Backdrop will attempt to upgrade your views, but there are some D7 views components that do not have comparable equivalents in Backdrop (those may show as having broken/missing handlers, and need to be updated).
  4. Check contrib projects.
    • Though all contrib projects should contain upgrade paths from Drupal 7 to Backdrop, it is possible that your site contains a use-case that has not yet been thoroughly tested. Test everything, and report any issues in the appropriate issue queue.

Upgrading from Drupal 6

We recommend using Drupal's built-in upgrade path to go from from Drupal 6 to Drupal 7 (which could be tricky), and then Backdrop's Built-in path to go from Drupal 7 to Backdrop CMS (which should be easy). Currently, there are no tools available to upgrade a Drupal 6 site directly to Backdrop.

Crossgrading from Drupal 8

We recommend using the same tools that would be used to go from Drupal 8 to Drupal 7 for Backdrop CMS: Migrate module, custom scripts, etc.