OPC IT. Managed services and web development in Canberra.

An introduction to Drush: The Drupal power tool

16 February 2015
Authored by: 
James Sinclair

What is Drush?

Drush is a tool that allows you to perform common Drupal tasks from the command line. According to the Drush project page:

Drush is a command line shell and scipting rinterface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt. To give a quick example, I can use Drush to enable a module by opening a command line and typing:

# cd /path/to/drupal/

# drush en views

Why use Drush?

So, why would you use Drush when Drupal already provides such nice user

interfaces (especially with D7)? There are two main reasons I use Drush: speed, and scripting.


Using a command line tool to do common tasks is generally faster than using the web-based interface. This is very well demonstrated by the Development Seed video: Drush: More Beer, Less Effort

If you don't have time to go watch that however, I'll provide a quick comparison.

Here is a list of things you need to do to install and enable the _views_ module manually with Drupal:

  1. Open a web browser
  2. Go to the project page: http://drupal.org/project/views
  3. Download the tarball
  4. Find the tarball in your file system and unzip it
  5. Move the unzipped contents to the appropriate folder in your Drupal installation
  6. Go back to the web browser and find the modules admin page
  7. Find the module in the list, check its box to enable it, and hit _Save_

Compare the above list with the steps to complete the task with Drush:

  1. Open a command line
  2. Type `cd /path/to/my/drupal/install`
  3. Type `drush dl views -y`
  4. Type `drush en views -y`

That's it. No searching through your _Downloads_ folder to find the zipped module; no scrolling through an enormous list of modules trying to find the one you just installed. Just three short commands.


The other advantage of command line tools like Drush is that you can run the commands from within a script. This is particularly handy if you find yourself doing a few things repeatedly. We will look at this in a little more depth later on, but suffice to say that a few well-written scripts can save you a lot of time and hassle.

Installing Drush

Even though Drush is listed as a module on the drupal.org website, it's not really a module. To install it, you need to download the tarball from the project page and unzip it somewhere sensible. On my Mac, I have it installed under `~/Library/drush`. **Note:** If you want to use Drush in a Windows environment, do not install it anywhere with a space in the file path. For example, installing Drush under `C:\Program Files\drush` is a bad idea. Try C:\drush` instead.

Once you have the package saved somewhere you will also need to add this location to your `$PATH` environment variable. This will save you having to type something like `~/Library/drush/drush` every time you want to run a drush command.[^path] Once you've done this, you should be able to fire up your command line and do the following:

# cd /path/to/drupal

# drush status

If your server is running, you should see a summary of some key information about your Drupal install.

There is a lot more to be said about installing Drush, and I thoroughly recommend reading the helpful `README.txt` file that comes included with the package. Of course, you already do that with everything you download from drupal.org, and this all goes without saying.

If you don't know how to do this, then I suggest this Tech-Recipes page if you're using a Mac or some form of \*NIX. If you're on Windows, then it's not too hard to find in the control panel, but if you get struck you could try this article.

Useful Commands with Drush

So, just what can you do with Drush? Here is a list of commands that I find handy:

Command | Description

`drush dl <module name>`  | Download and install a drupal module (defaults to the `sites/all/modules` directory)

`drush en <module name>`  | Enable a module

`drush dis <module name>` | Disable a module

`drush up`                | Check for available updates, download updated modules and run `update.php`

`drush up <module name>`  | Check to see if the specific module needs updating, and if so, download it and run `update.php`

`drush sql-dump --result-file=db-backup.sql` | Dump the entire Drupal database into a file called `db-backup.sql`. In other words, backup your database.

`drush sql-cli < db-backup.sql` | Connect to the database server and run the commands in `db-backup.sql`. In other words, restore the database from `db-backup.sql`

`drush cc all`            | Clear all caches

`drush vset preprocess_css 0 --yes` | Turn off CSS caching (useful when developing themes)

`drush vset preprocess_js 0 --yes` | Turn off JavaScript caching

`drush cron`              | Run cron

`drush vset site_offline 1 --yes` | Put a site into maintenance mode (D6 only)

`drush vset maintenance_mode 1 --yes` | Put a site into maintenance mode (D7 only)

`drush vset site_offline 0 --yes` | Take a site out of maintenance mode (D6 only)

`drush vset maintenance_mode 0 --yes` | Take a site out of maintenance mode (D7 only)

Drush Site Aliases

One of the very cool things about Drush is that, if you have SSH keys installed, then you can run commands *remotely*. That is, if I have Drush installed on both my local machine, and another remote machine, I can tell Drush to SSH into my remote server and run a command there. For example:

# drush username@server.com/path/to/drupal#mysite.com status

This example was copied from the very helpful article Drush 3.0: More Powerful, Flexible, and Magical by Adrian Rossouw of Development Seed.

Now, you may be thinking that seems like a lot to type out---you might as well just SSH into the server yourself and run Dush there---and you would be right. This is where _Site Aliases_ come in.

What is a site alias?

Site aliases are shortcuts to specify that you want to run a Drush command on a specific Drupal site. For example, it would allow you to type the following instead of the long command above:

# drush @mysite status

Drush would then look up the details for *mysite*, SSH into the remote host, run the `status` command and display the results.

How to set up site aliases

Site aliases do take a little bit of work to set up, but they are definitely worth the effort. To get started you'll need to create a directory called `.drush` inside your _home_ directory. To find out what your home directory is, type the following:

    # cd ~

    # pwd

Inside the `.drush` directory you'll need to create a file called `aliases.drushrc.php`.

Let's assume for the sake of the example that you have a Drupal site running on your local machine at `localhost`, and another running on a server at `example.com`.

To set an alias for the local site, save the following into your `aliases.drushrc.php` file:


  $aliases['local'] = array(

  'uri'  => 'localhost',

  'root' => '/path/to/my/drupal/install, // This must be a full full path, not a relative one



Once this is done, you should be able to type `drush @local status`, and get a status listing. Now, that may not seem all that exciting, but once you have this alias installed, you can run that command from _whatever happens to be your current directory_. So, I can, for example, type:

# cd ~/my_random_directory

drush @local status

Drupal version : 7.0

Site URI localhost


# cd some/other/random/directory

drush @local status

Drupal version [...]

Now, that's not bad, but as mentioned above, the real magic is being able to do this from your local machine, without having to log in. To set this up, we need set up a few things first:

  1. First, you will need Drush installed on your remote machine and added to the `$\_PATH` (as described above).
  2. You will also need to created an SSH key pair so that Drush can log in to the remote server securely, without having to ask you for a password.[^sshkeys] You then need to add a slightly longer alias entry to your `ailases.drushrc.php` file:


        $aliases['remote'] = array(

          'uri'          => 'example.com',

          'root'         => '/path/to/my/drupal/install',  // This is the path on the remote server

          'remote-host'  => 'example.com',

          'remote-user'  => 'myusername',

          'path-aliases' => array(

            '%files' => 'sites/default/files',



Once all this is done, you should be able to type `drush @remote status` and get the status of your remote server. You can also run commands like `drush @remote up`, or `drush @remote en views`. This can come in very handy when, for example, you need to quickly clear the cache on a remote server.

If you're looking for how to get started with this, check out Matt Wynne's post, Quick and Easy Password-less SSH Login on Remote ServersOr, if you're on Windows using Putty, you can find slightly more detailed instructions for SSH keys with Putty on Daily Iteration.

Using Drush in a script

One of the really useful things about Drush is that because you can run it from the command line, you can also run it from a script. For example, if you have a number of site aliases set up and you'd like to backup the database on each of them, you could write a script something

like the following:



  $aliases = array( '@alpha', '@beta', '@gamma', '@epsilon' );

  foreach ($aliases as $alias) {

    shell_exec("drush $alias sql-dump --result-file=my-backup-file.sql");


Then, from the terminal, you could simply type `php backup-drupal-sites.php` to backup the database across all four sites.

If you'd like more on the kinds of things you can do with Drush in a script, check out [Drupal Release Management with Drush and Git](/web-development/drupal-release-management-drush-and-git)

The limitations of Drush

While Drush is very useful, there are still some things that you can't do with Drush. At the moment, for example, (as far as I know) you can't create new nodes with Drush. It would be very nice to one day type commands like:

    # drush content-create-node 'Page' < MyNewPage.markdown

      New node created with id 321

    # drush content-publish-node 321

And have it create a new page for me. However, it would be an incredibly complicated feature to create, so I don't see it happening any time soon (although this Node Export feature request looks very interesting.

Probably the biggest current limitation of Drush though, is Windows support.

Drush and Windows

Drush has very limited Windows support at the time of writing, and the Drush development team are looking for people to help them sort it out. If you'd like to jump in and help, the place to start reading is: http://drupal.org/node/766080

For the moment though, I can tell you that a lot of useful commands _do_ work in Windows. These include:

    drush dl

    drush status

    drush core-cron

    drush vset

    drush cc

    drush vget

    drush sql-cli

A couple of very useful commands that don't work properly yet are:

* `drush updb`: This one is the most inconvenient for me. So much so

   that I hacked together a very dodgy patch to get the `updb` command

   working (though YMMV). If you're interested, check out http://drupal.org/node/766080#comment-4185454

* `drush up`: This command mostly works, but unfortunately it depends on

   `updb` to run database updates. So, it will download the new files

   for you, but it won't run database updates.

* `drush sql-dump`: This also mostly works, but in my testing I found

   that it doesn't deal with the `--structure-tables-key` option very

   well. So, if you're happy to use it without that option, then it

   works well enough.

And finally, anything that requires SSH access is going to fail, so most of the usefulness of site aliases goes away. I _have_ found a way around this, but will save that for another post.

To sum up, you can use Drush on Windows, but be careful. **Update:** It looks as if Drush 5.x will solve many of the problems with drush on Windows.


Finally, here are a few places to look if you'd like to get more information on how to use Drush: