Manage Drush Versions on Pantheon
Learn about Pantheon's default Drush version and how to implement site-local usage.
This section provides information on Drush versions and site-local usage.
Pantheon runs Drush versions based on your Drupal version:
- Drupal (Latest Version): 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.
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 10 is available with the addition of the
pantheon.ymlfile, or for site-local installation. It requires Drupal 9 or higher, Composer, and PHP 7.1 or higher.Drush 9 and Drush 10 only work on Drupal 8.4 and higher.
Drush 8 Drush 8 is the only recommended version to use in your
pantheon.ymlfile. It is compatible with Drupal 7.Drush 5 and Drush 7 are available on Pantheon if needed. However, both versions are listed as unsupported by the Drush maintainers, and should be avoided unless absolutely necessary.
We highly recommend running Drush version 8.3.2 or higher when running Drush locally.
Drush Requirements and Compatibility
| Drush Version | PHP Version | End of Life | Drupal 7 | Drupal 8 | Drupal (Latest Version) |
|---|---|---|---|---|---|
| 11* | 7.4+ | TBD | ❌ | ❌ | ✔ |
| 10 | 7.1+ | Jan. 2022 | ❌ | Compatible, unsupported | Compatible, unsupported |
| 9 | 5.6+ | May 2020 | ❌ | Compatible, unsupported | ❌ |
| 8 | 5.4.5+ | Nov. 2022 | ✔ | Supported, not recommended | ❌ |
| 7 | 5.3.0+ | July 2017 | Compatible, unsupported | ❌ | ❌ |
| 6 | 5.3.0+ | Dec. 2015 | Compatible, unsupported | ❌ | ❌ |
| 5 | 5.2.0+ | May 2015 | Compatible, 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
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.
Change your site's Drush version in the
pantheon.ymlfile:pantheon.ymlapi_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.
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.
Check for an outdated configuration file,
policy.drush.inc, in your local~/.drushdirectory.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 the latest version of Drupal with Drush 11 installed as a site-local Drush if you manage your site with Composer.
Our default Composer-managed upstream has a start state for this dependency that will also work with Drush 12 when it is released.
"drush/drush": "^11 || ^12"Refer to Pantheon's Drupal Composer-Managed upstream for a complete example of the composer.json file.
Permissions
Site-local Drush requires executable permissions. Follow the steps below if you encounter permission denied errors when running Drush commands.
Adjust permissions on the Drush executable:
chmod +x vendor/bin/drushCommit 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:127Configure a newer version of Drush as documented above to resolve this error.