Skip to main content

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

bash
 
git add . git commit -m "Initial commit of Drupal site to Pantheon" git push origin master

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

 
terminus drush my-drupal-migration.dev cr terminus drush my-drupal-migration.dev updb -y

Optional: Enable Multidev for Team Dev Workflows

 
terminus multidev:create my-drupal-migration dev feature-branch

🔒 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

Tags

Recent Blogs

The latest version of PHP is 8.4.4, which was released on February 13, 2025. PHP 8.4 is the…Read more

Drupal 11.0.0 has officially launched, marking an exciting milestone for both current users and…Read more

As a WordPress developer with a focus on enterprise-level solutions, the idea of a multi-block…Read more