Manage Drush Versions on Pantheon

Understanding Drush Installation Location

Drush is installed in two places on within the infrastructure of a modern Drupal site on Pantheon:

• The site-local installation is the one that is managed by a site's Composer files (composer.json and composer.lock) in the root of the site's git repository. This installation is the one teams should focus on.
• Secondarily, there is also a global installation of Drush that can be controlled by a site's pantheon.yml file.

Allowing for different versions of Drush between the global and site-local level is valuable when many sites are present within the same runtime environment. Pantheon's containerized infrastructure makes this distinction more academic than practical for interactions on the platform. This separation between global and site-local installations relevant when working with local development environments or other platform providers. For modern Drupal sites the global Drush installation acts primarily as a wrapper to invoke the site-local version.

Drupal 9, 10 and Beyond

For most teams running a modern version of Drupal, the site-local version of Drush is only one to pay attention to. The composer.json file used by newly created Drupal 9 and 10 sites is set to allow Drush 11 or 12 as the site-local version.

Changing the Site-Local Drush Version

To change the site-local version of Drush run a composer command to update the version of Drush in the composer.json file. For instance, to set the site-local version of Drush to 11, run the following command:

composer require drush/drush:^11

Drupal 7

For older versions of Drupal (7 and earlier), the global installation of Drush is the only one available.

Changing the Global Drush Version on Pantheon

To change the global Drush version (which will still invoke the site-local version of Drush when available), update the drush_version key in the pantheon.yml file. For instance, to set the global version of Drush to 8, add the following to the pantheon.yml file:

api_version: 1

drush_version: 8

remote:
remote: PANTHEON ERROR:
remote:
remote: Changes to `pantheon.yml` detected, but there was an error while processing it:
remote:
remote: pantheon.yml:
remote: Validation failed with error:
remote: >   11 is not one of [5, 7, 8, 9, 10]
remote:
remote: while validating the following value:
remote: >   11
remote: >   ...
remote:
remote: To learn more about pantheon.yml, please see https://pantheon.io/docs/pantheon-yml/

Compatibility and Requirements

See the Drush Drupal Compatibility chart for version compatibility information. Consider the following information when determining which Drush version is best suited for your site.

Drush Requirements and Compatibility

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

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.

Verify Current Drush Version Interacting with Your Drupal Site

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

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

This command will return the version of Drush running on your site which will report the site-local version if it is present, otherwise it will report the global version.

Permissions

Site-local Drush requires executable permissions. While this is typically handled automatically by Composer, you may need to adjust permissions manually, especially if you are not using Integrated Composer install dependencies on Pantheon and are instead committing the vendor directory to your repository.

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

• Avoiding “Dependency Hell” with Site-Local Drush (Blog)
• The pantheon.yml Configuration File