Drush Site Aliases for Drupal 8, Drupal 9

Last updated December 6, 2021

Drush commands are commonly run in the Drupal docroot, the directory where Drupal's files live. This is a relatively simple task on your local development environment. But if you're working on multiple sites and each of those sites has one or more remote environments that you connect to via SSH, workflows quickly become complicated. Creating and using Drush site aliases allows you to run Drush commands on any site, local or remote, that you have credentials to access, from any location on your computer that has access to a Drush executable.

Imagine you've got a Drupal project with dev, test, and live environments in the cloud somewhere. And you need to clear the cache on the dev environment. You could SSH to that environment, and execute drush cr there. Or, after configuring a site alias you could do something like:

drush @provider.dev cr -y

And Drush will connect to the remote environment and clear the cache.

Site aliases allow bundling the configuration options (--uri, --root, etc.) for a specific remote server under an alias. This reduces the amount of typing required. Even more importantly, it helps teams agree on a common definition for environments like @dev, @test, and @live by committing their configurations to version control.

In this tutorial we'll:

  • Define what a Drush site alias is
  • Understand the use case for aliases
  • Learn how to configure and use Drush site aliases

By the end of this tutorial, you should understand how Drush site aliases work, how to create Drush site aliases, and how to use them in a Drush command.