Manage Drush Versions on Pantheon

Learn about Pantheon's default Drush version and how to implement site-local usage.

Discuss in our Forum Discuss in Slack

This section provides information on Drush versions and site-local usage.

Pantheon runs Drush versions based on your Drupal version:

  • Drupal 9: Drush 10 (for newly created sites)
  • Drupal 7: Drush 8 (for newly created sites)

Available Drush Versions

Pantheon currently supports the following Drush versions:

  • Drush 11
  • Drush 10
  • Drush 8

We recommend managing your site through Composer. Visit the Build Tools Workflow for information on how to use Composer to manage Drupal sites on Pantheon, or the Convert to Composer guide to convert an existing site to a Composer-managed site.

Verify Current Drush Version

You can use Terminus to verify the current version of Drush running on your Pantheon site:

terminus drush <site>.<env> -- status | grep "Drush version"

Compatibility and Requirements

Drush only supports one install method. Your Drupal site is required to be built with Composer and your Drush must be compatible and listed as a dependency. Consider the following information when determining which Drush version is best suited for your site:

 Note

We highly recommend running Drush version 8.3.2 or higher when running Drush locally.

Drush Requirements and Compatibility

Drush VersionPHP VersionEnd of LifeDrupal 7Drupal 8Drupal 9
11*7.4+TBD
107.1+Jan. 2022Compatible, unsupportedCompatible, unsupported
95.6+May 2020Compatible, unsupported
85.4.5+Nov. 2022Supported, not recommended
75.3.0+July 2017Compatible, unsupported
65.3.0+Dec. 2015Compatible, unsupported
55.2.0+May 2015Compatible, unsupported

*Drush 11 is not available through pantheon.yml. Drush 11 can only be used through a site-local installation.

Refer to our guide on Upgrading PHP Versions for more information.

Configure Drush Version

  1. Refer to Available Drush Versions and Drush requirements before you modify a site's Drush version. Remember that not all versions of Drush are compatible with all versions of Drupal.

  2. Change your site's Drush version in the pantheon.yml file:

    pantheon.yml
    api_version: 1
    
    drush_version: 8

Now your site’s Drush version is managed via pantheon.yml. This allows Drush to be version controlled and deployed along with the rest of your code.

 Note

Create the pantheon.yml file if it does not already exist. If a pantheon.upstream.yml file exists, do not edit it. It is used by the upstream updates repository and will cause a merge conflict if modified.

Troubleshoot Your Drush Version

Occasionally, the correct version of Drush is not called even after updating the Drush version in pantheon.yml.

The Pantheon platform always prefers the site-local Drush or other local settings over the setting in the pantheon.yml file.

  1. Check for an outdated configuration file, policy.drush.inc, in your local ~/.drush directory.

  2. Remove the file, or comment out its contents to resolve the issue.

Executing Drush on the platform via a terminus drush command will use the version of Drush specified in pantheon.yml, unless a site-local version is present.

Site-local Drush Usage

We recommend that you use Drupal 9 with Drush 11 installed as a site-local Drush if you manage your site with Composer.

Do not select any major version of Drush lower than 8.3.2, 9.7.1, or 10.2.0.

Refer to Avoiding “Dependency Hell” with Site-Local Drush for more information.

Permissions

Site-local Drush requires executable permissions. Follow the steps below if you encounter permission denied errors when running Drush commands.

  1. Adjust permissions on the Drush executable:

    chmod +x vendor/bin/drush
  2. Commit and push this change to your Pantheon site.

Drush 5 on Older Sites

Drupal sites created on Pantheon in late 2015 or earlier that do not have drush_version defined in pantheon.yml may default to Drush 5. In this case, you may see the following error:

{{Uncaught Error: Call to undefined function mysql_connect() in /etc/drush/drush-5-extensions/pantheon.drush.inc:127

Configure a newer version of Drush as documented above to resolve this error.

More Resources