Drush aliases

Submitted by Erik on Tue, 06/14/2011 - 19:11

I'm trying to get a better handle on Drush aliases, so figured it would help to write out my findings and thoughts. This post may update as we go, so look back for changes.

Drush context

Drush runs in specific contexts, if Drush can tell that it's in a Drupal root somewhere, it will assume the --root=/path/to/that/Drupal. It can also detect if you're within a sites/subsite directory and will set --uri=subsite as well. This is very handy as I am often doing other command line tasks in the terminal window, so if I'm already in a specific location, Drush will assume that location as the context.

cd ~/Sites/drupal/sites/subsite.vmdev
drush status

is equivalent to:

drush --root=~/Sites/drupal --uri=subsite.vmdev status

Not much savings, but when you have to clear caches, run cron, check watchdog entries multiple times, it's nice not to have to add those all the time.

Drush Aliases

The other way of setting context is with Drush aliases. In the examples directory, there is an example.aliases.drushrc.php file. Copy this file either to the .drush directory in your home directory or to the same directory where the drush script lives. There are a couple of other places that Drush will automatically search for alias files and they're documented in example.aliases.drushrc.php.

To begin with, rename the copied file to aliases.drushrc.php. There are other naming patterns that you can use, but we'll get to those later.

A basic drush alias is an associative array that defines all the necessary properties of the site that you're going to try to alias.

Let's make an example alias to our subsite.vmdev site which is on my local machine and in the main Drupal multisite. To define an alias, you create a keyed item in the $aliases array. The key should be what you would like to call the alias. In our case, subsite.

['subsite'] = array(
// definition will go here.

Once we have the definition, we need to add the Drupal root and the URI to the definition:

['subsite'] = array(
'root' => '/Users/erikp/Sites/drupal',
'uri' => 'subsite.vmdev',

This allows drush to know which specific drupal site we're referring to no matter what directory we happen to be in. So now we can run commands against the new alias by using the @aliasname syntax with drush:

drush @subsite status

Remote aliases

One powerful feature of drush is its ability to communicate with Drupal sites on other servers over SSH. Aliases can take advantage of this as well by using the remote-host and remote-user keys in the site alias definition:

['real_site'] = array(
'remote-host' => 'myserver.eporama.com',
'root' => '/home/www/drupal-6.22',
'uri' => 'mysite.eporama.com',

This would create an alias to the website that has a URL of mysite.eporama.com which lives on the server myserver.eporama.com and has a different path to where Drupal is installed.

Now, from my local machine, not logged into the remote machine, I can still use drush:

drush @real_site status

MySQL Dumps

If you're going to be running drush sql-dump or drush sql-sync, it helps to let drush know where you'd like to have the dump files stored. You can do this by specifying a dump-dir. However, dump-dir is actually a sub variable of path-aliases.

['real_site'] = array(
'remote-host' => 'myserver.eporama.com',
'root' => '/home/www/drupal-6.22',
'uri' => 'mysite.eporama.com',
'path-aliases' => array(
'%dump-dir' => '/home/erikp/drush-dumps',

When sql-sync runs, it first dumps the database on the source server, then copies the dump file to the target server, and finally imports the dump file into the target database server. The dump-dir is where it will store these dump files. If you call for a second sql-sync within 24 hours, drush will assume that the existing dump file is good enough. If you need to get a fresh sql file, you can add the parameter --no-cache.

To sync two databases, you specify the source database first and then the target database:

drush sql-sync @real_site @subsite

Parental Aliases

Once you have a significant number of aliases defined (probably more than two), you'll start to notice that there is a lot of repetition. Every site on the same multisite needs the same root the same dump-dir, etc. Luckily, you can take these common pieces and group them together in a single alias and then use that alias inside of other aliases.

['local-site'] = array(
'root' => '/Users/erikp/Sites/drupal-6.22',
'path-aliases' => array(
'%dump-dir' => '/Users/erikp/drush-dumps',
$aliases['subsite'] = array(
'parent' => '@local-site', // this refers to the alias defined above
'uri' => 'subsite.vmdev',

The subsite alias inherits the information from the local-site alias.

In my aliases file, I have defined three "parent" aliases on which all of my other aliases are based. They are local, dev, and prod which give the remote-host, root, dump-dir for my local machine and our development and production servers. Then for each new site, I can quickly create three new aliases one for each environment:

['local.new-site'] = array(
'parent' => '@local',
'uri' => 'new-site.org',
$aliases['dev.new-site'] = array(
'parent' => '@dev',
'uri' => 'new-site.org',
$aliases['prod.new-site'] = array(
'parent' => '@prod',
'uri' => 'new-site.org',

Multiple Alias files

You can also keep multiple alias files if that would help keep things more organized for you. I have a file for work Drupal sites (edc.aliases.drushrc.php) and a separate file for non-work sites that I work on (my.aliases.drushrc.php). This way, I can share the work site alias file with the other developers in our office and it helps keep things organized and makes sure that when I recommend running drush @oursite cc all that the alias will be the same for each of us.

Drush will look for these files in a number of places, but the most common is to put them in a folder called aliases in your $HOME/.drush directory. If you would like to have them in a specific location, you can specify any path you want in drushrc.php.


Hi, thanks for a great summary of this topic on site aliases. I am able to execute drush commands when I ssh to my remote site but when I try to execute drush commands using my drush site aliases I always get the following:

The command could not be executed successfully (returned: jailshell: [error]
drush: command not found
, code: 0)

What could the problem be? Drush is working but not when I use the site alias. Is it my webhost?
thanks in advance

When you run remote commands, you're not actually fully logging into your shell account on the server. If you define where you're finding drush in .bash_profile, then this file isn't loaded when running an "interactive shell". You need to make sure to define where drush is in .bashrc.

Problem solved:

It turns out it was the drush alias (as opposed to the site alias) as defined in .bashrc and .bash_profile on the remote server that needed more PATH info added.
Thanks for the support.

subbu (not verified)

Fri, 08/26/2011 - 04:54

How do you set aliases globally ?
Let us say we have 5 users to the linux server, it would be redundant for all of them to create a .drush folder.


From the example.aliases.drushrc.php file, it tells us:

* Drush will search for aliases in any of these files using
* the alias search path.  The following locations are examined
* for alias files:
*   1. In any path set in $options['alias-path'] in drushrc.php,
*      or (equivalently) any path passed in via --alias-path=...
*      on the command line.
*   2. If 'alias-path' is not set, then in one of the default
*      locations:
*        a. /etc/drush
*        b. In the drush installation folder
*        c. Inside the 'aliases' folder in the drush installation folder
*        d. $HOME/.drush
*   3. Inside the sites folder of any bootstrapped Drupal site,
*      or any local Drupal site indicated by an alias used as
*      a parameter to a command

My .drush/aliases file is essentially 2d. But to get a global file, you can simply store it in /etc/drush or in the shared drush folder itself. You can also define where the aliases should be looked for via the drushrc.php file, but you only need to do that if you're going to keep them in a non-standard location. And you can set up global aliases and still have more of your own in ~/.drush.

Hope that helps

manarth (not verified)

Tue, 06/12/2012 - 11:37

I discovered today that if you're using Powershell, the site-alias syntax needs a tweak: strings beginning @ are treated as shell variables, and Powershell tries to interpolate them. Wrapping the site-alias in double-quotes solves the problem: drush "@subsite" status.

Ignacio Bonelli (not verified)

Fri, 08/03/2012 - 12:36

Thanks a lot for sharing this! I've been reading documentation and trying stuff, but I could not get a good context. Your example gave me the clue I was looking for. All I got before was "Command status needs a higher bootstrap level to run" :P

Cash (not verified)

Sun, 07/21/2013 - 16:04

Hey Erik, this page comes up pretty high on google for "create new drush alias". Props on the SEO!!

Can I suggest an update to the article?

Drush use @alias

This will set the alias for the terminal session, then can run for instance drush sa from anywhere without need to add alias every time. This is especially good when developing a site. The drush readme has some info on how to make the current alias show up in your prompt, such as

~/Sites/example.localhost/docroot [@example.localhost] $

Technically, "use" is an alias to the "site-set" command. One gotcha is to get out of a site-set, you use the "site-reset" command.

I always forget when I've set one... Wonder if you can influence your PS1 environment var with the current site-set... I do that with git to remind me which branch I'm on.

Add new comment

The content of this field is kept private and will not be shown publicly.

Filtered HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <img src alt height width> <pre>
  • You may post code using <code>...</code> (generic) or <?php ... ?> (highlighted PHP) tags.
  • Lines and paragraphs break automatically.
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.