Migrating a Drupal Site to Pantheon: Step-by-Step Guide with Code

Migrating your existing Drupal 9 or 10 site to Pantheon unlocks powerful benefits — high-performance hosting, automated DevOps workflows, and scalability built for enterprise. In this guide, you'll learn how to migrate a Drupal site to Pantheon using Git, Drush, and Terminus, complete with commands, gotchas, and configuration tips.

🧰 Prerequisites

Before you begin, ensure you have:

• A working Drupal 9 or 10 site (local or hosted).

• A Pantheon account.

• Installed CLI tools:

  • Terminus: Pantheon command-line tool.

  • Drush: Drupal command-line tool.

  • Git

🚀 Step-by-Step Migration to Pantheon

Step 1: Create a New Site on Pantheon

terminus auth:login
terminus site:create my-drupal-migration "My Drupal Migration Site" drupal-recommended

Replace my-drupal-migration with your preferred machine name.

Step 2: Clone Pantheon Site Locally

terminus connection:set my-drupal-migration dev git
git clone git@ssh.dev.mydrupalmigration.pantheon.io:codes.git my-drupal-migration
cd my-drupal-migration

Step 3: Prepare Your Local Drupal Site

You want your site to follow the Drupal recommended project structure:

composer create-project drupal/recommended-project my-site

Now copy custom code, themes, and modules into your new Pantheon-compliant structure:

cp -r ../old-site/web/modules/custom web/modules/custom
cp -r ../old-site/web/themes/custom web/themes/custom

Also migrate:

• sites/default/files

• Configuration: sync/ folder if you're using config management

Step 4: Update Pantheon pantheon.yml

Make sure your pantheon.yml exists in the root directory

api_version: 1
web_docroot: web
php_version: 8.2
database:
  version: 10.4

Add any custom settings if needed (e.g., Redis, Solr).

Step 5: Push Code to Pantheon

Pantheon will now build and deploy your site using its build tools.

Step 6: Import the Database

1. Export from old site:

   bash

    

   drush sql:dump > site.sql

2. Upload and import to Pantheon:

    

   terminus import:database my-drupal-migration.dev site.sql

Step 7: Sync Your Files

1. Archive files:

    

   tar -czf files.tar.gz sites/default/files

2. Upload to Pantheon:

    

   terminus import:files my-drupal-migration.dev files.tar.gz

Step 8: Clear Cache and Run Updates

✅ Optional: Enable Multidev for Team Dev Workflows

🔒 Secure It (Optional)

Set up HTTPS, Redis, and any IP allowlists through Pantheon dashboard settings or pantheon.yml.

✅ Conclusion

Migrating a Drupal site to Pantheon is more than just a move — it's a chance to modernize your architecture. With Pantheon’s robust infrastructure, Git-based workflows, and CLI automation tools, your Drupal project becomes easier to manage, test, and scale.

This migration approach works seamlessly for:

• Drupal 9 and 10

• Composer-managed projects

• Sites needing robust CI/CD and environment control