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

A glimpse at the journey from Drupal 10 to Drupal 11

Read more

Indeed, CKEditor 5 and Drupal 10 form a powerful duo for content creation, enhancing the…Read more

The significance of Drupal 10 lies in its seamless and easy upgrade process. Unlike major…Read more