Drush - command line shell for Drupal

With Drupal adopting the use of Composer to manage code as from Drupal 8 upwards, it has become a matter of a single composer require command to install packages that would have taken lots of manual calculations, libraries hunting, downloading, extracting and reuploading, to get installed. Now all you have to do is ask Composer to get the package for you and it fetches the appropriate versions and libraries and dependencies and places them in the right directories for you, so you can go straight to using the packages without worrying about version conflicts and the right dependencies.

This has also affected the installation of Drush. Formerly one has to create the 'drush' folder, download the installer and run the installation; but now all you need is to run the single Composer command,

composer require drush/drush

and sit back while Composer installs Drush for your Drupal instance in the right place.

Composer installs Drush inside the 'vendor' directory in the project-root, specifically at 'vendor/bin/drush' so depending on your pwd (present working directory) within your project, you have to call Drush relative to it's location. If you are on the project-root you will call it with vendor/bin/drush and if you are in the docroot you will use ../vendor/bin/drush.

By the way, what is Drush?

Drush is a command line utility for Drupal, it is Drupal's Swiss Army Knife. It is a powerful tool in the hands of a Drupal developer. Drush has lots of indispensable commands to interact with Drupal. With Drush you can install Drupal, enable modules and themes, uninstall modules and themes, create users, create content, update Drupal, update the database, clear caches, put site in maintenance mode, reset passwords, view error logs even when site is not accessible in browsers, backup site files, restore site from backup, backup database, restore database from backup, export configuration, import configuration, generate boilerplate code and lots more! Like I said, it is a Swiss Army Knife in the hands of a Drupal developer.

1. Drush Launcher makes drush command globally available in your $PATH

UPDATE: Drush Launcher is now deprecated as at August 19, 2023. There is on-going effort for a replacement.

UPDATE: Here's a fork of the project that supports Drush 12. So it has been brought back to life.

Using vendor/bin/drush works but traditionally Drush ought to be called with the drush command and so there is Drush Launcher, 'a small wrapper around Drush for your global $PATH'. What Drush Launcher does is to make the drush command available globally on your local machine so you can execute Drush commands from anywhere on your machine, but it must be in the project-root of a Drupal instance. Composer places project-specific copies of Drush in the 'vendor' directory of each project, this is the copy that is called to execute on the project, so you should have Drush installed per project and you can use vendor/bin/drush to execute Drush commands but with Drush Launcher installed on your machine, you will use the traditional drush command. This should be more convenient.

To install Drush Launcher use the following steps:

1) Download drush.phar on your machine. You should do this on a location (path) listed in your $PATH or you add your path to $PATH.

curl -OL https://github.com/drush-ops/drush-launcher/releases/latest/download/drush.phar

If on a Linux machine use this instead:

wget -O drush.phar https://github.com/drush-ops/drush-launcher/releases/latest/download/drush.phar

2) Make the file executable: chmod +x drush.phar

3) If using Windows, create a drush.bat file in the same folder as drush.phar with the following lines. This gets around the problem where Windows does not know that .phar files are associated with php:

@echo off
php "%~dp0\drush.phar" %*

4) You are done! You should now be able to use the drush command globally on your machine!

Note: I do get errors with drush updatedb and this seems to be an issue as regards the Windows environment, so I will use vendor/bin/drush updatedb but most other Drush commands work. Using Drupal 9.3.3, Drush Launcher 0.7.4 and Drush 10.6.1 I found this issue is gone.

2. Using Bash Alias

Now, you would have lots of Drupal projects on your laptop and having Drush Launcher means you can use the drush command within any of these projects but it's a bit different when you move to remote server, at least with the kind of hosting environments we use for our projects being shared host plans and VPS plans, we usually have one, and rarely two or three projects within each host account. This does not make much sense installing Drush Launcher just for one project, so we use Bash aliases to alias drush to vendor/bin/drush and same purpose of Drush Launcher is achieved.

To make a Bash alias of drush mapping to vendor/bin/drush we usually use the following commands:

1) Move to the project root (should be the home directory of your account).


2) Create the alias. Alternatively you can open [dot]bashrc file with your favorite editor and add the line alias drush='~/vendor/bin/drush' under 'User specific aliases and functions', save and close the file.

echo "alias drush='~/vendor/bin/drush'" >> .bashrc

3) Load the newly added alias into your current Bash session. Alternatively, close and re-open your terminal for it to reload its configuration file.

source .bashrc

4) That's it! You can now use the drush command from any folder within your project.

If you know Linux commands so well you can actually get funky with this. For example, you can add the time command so Drush also tells how long it took to execute the command. This can be useful in some cases e.g. to compare the speed of different environments.

To add the time command, your alias will look like,

echo "alias drush='time ~/vendor/bin/drush'" >> .bashrc

With this, executing drush cr will give output like,

drush cr
 [success] Cache rebuild complete.

real    0m3.647s
user    0m2.778s
sys     0m0.284s

So you see, you can get real funky with this.

I hope this tip is useful for you.

Happy Drupaling! Sorry, Drushing!

Last updated: May 10, 2024