Drush is the command line shell and Unix scripting interface for Drupal. The most common way to install Drush is to install it on a per-project basis using Composer. We'll walk through the steps to do that, as well as how to set up the Drush Launcher tool (to make it possible to execute Drush commands without having to specify a full path to the executable).
In this tutorial we'll:
- Install Drush
- Install Drush Launcher
- Verify it worked
By the end of this tutorial you'll have Drush installed.
Goal
Install Drush and verify it's working.
Prerequisites
Install Drush using Composer
This assumes that your Drupal codebase is managed using Composer. The current recommendation is to install Drush on a per-project basis. This allows for having different versions of Drush installed for different projects. This is a best practice because different versions of Drush are compatible with a particular set of Drupal versions.
Run composer require
In most cases it's best to install Drush as a development dependency. From the root directory of your project run the following command:
composer require --dev drush/drush
Once that's completed run the command ./vendor/bin/drush --version
to verify it worked.
./vendor/bin/drush --version
# > Drush Commandline Tool 10.6.2
(Optional) Install Drush Launcher
Rather than have to type ./vendor/bin/drush
or the relative path to the executable in order to execute Drush commands, install the Drush Launcher. That is a small program which listens on your $PATH
and passes control to a project-specific Drush installation in the /vendor directory of the project associated with your current working directory. (The directory you're running drush
within is somewhere in your project's directory hierarchy.)
This requires installing a PHP Phar. The following steps are derived from the documentation at https://github.com/drush-ops/drush-launcher.
Download the lastest stable release
You may manually download or use command-line tools to get drush.phar.
Manual download
Using a browser, navigate to https://github.com/drush-ops/drush-launcher/releases/latest and download drush.phar to a suitable "global" location (outside of a Drupal project), like your user's home or sites directory.
Download via CLI
Mac OS
curl -OL https://github.com/drush-ops/drush-launcher/releases/latest/download/drush.phar
Linux
wget -O drush.phar https://github.com/drush-ops/drush-launcher/releases/latest/download/drush.phar
Make downloaded file executable
chmod +x drush.phar
Move drush.phar to a location listed in your $PATH
Using the mv
command, move_drush.phar_ to a location listed in your $PATH
(echo $PATH
to see a list of locations) and rename it to drush
.
sudo mv drush.phar /usr/local/bin/drush
Windows users: Create a drush.bat file in the same folder as drush.phar with the lines below. (This gets around the problem where Windows does not know that .phar files are associated with php.)
@echo off
php "%~dp0\drush.phar" %*
(Optional) Export an environment variable as a fallback
When Drush can't find a local Drupal site, the launcher usually throws a helpful error instructing you to navigate to somewhere within a Drupal project or to add --root=/path/to/drupal
to the drush
command, so Drush knows where your site is located. You may avoid the error and hand off execution to a global Drush (any version) by exporting an environment variable.
export DRUSH_LAUNCHER_FALLBACK=/path/to/drush
Test it out
Use drush --version
to verify it worked.
You no longer need to specify ./vendor/bin/
. As long as you're somewhere within a Drupal project's directory structure the Drush Launcher will locate the copy of Drush in ./vendor/bin/drush and call it.
Update
The Drush Launcher Phar is able to self-update to the latest release when you update Drush.
drush self-update
Recap
In this tutorial we learned how to use Composer to install Drush as well as how to use the Drush Launcher tool to make it easier to execute Drush commands without having to provide a full path to the executable.
Further your understanding
- Run the
drush
command with no arguments to see a list of available Drush commands. - Read the Drush Launcher project README for additional tips and information.
Additional resources
- Drush documentation (drush.org)
- Drush Launcher (github.com)