How to Install Drupal 8 with Composer, then Set Up Drush

I’ve been looking into Drupal 8 since… well, DrupalCon Portland, and man, has it changed over time. Even though D8 has been a stable release for some time now, I’ve been focused on a Drupal 7 contract, so I’ve just recently begun my real foray into its practical application.

The last time I installed Drupal 8, there wasn’t any integration with Composer (whoa, it’s been that long?). So when I went to install a local environment a couple weeks before DrupalCon Baltimore to have a foundation to work off of, I was a little out of my element. On top of that, there wasn’t a comprehensive guide to installing Drupal the “recommended way.” I’ve documented the steps I took to install, and have included my sources so that you can check out all the most up-to-date info.

The reason we use Composer for our D8 builds is because of the way Drupal 8 handles modules. We only want to push the work we do to our repository, so we install modules through composer require, and keep them out of the codebase.

How to Install Composer

Composer requires PHP 5.3.2+ to run (but you should run PHP 7 if you can, it’ll improve site speed).

Additionally, you will need Git (which you likely already have), SVN, Fossil or HG to grab the version-controlled package. There are also zip downloads if all of that is Latin to you. If you aren’t already using Git, I highly recommend trying it out.

At, there are four steps for you to follow. I’ve copied the syntax below with some instruction, but please keep in mind that 1) this code won’t work as is —I’ve removed some keys to adhere the publisher’s request not to distribute the code, and 2) these instructions might change in the future. For the latest instructions on installing Composer, make sure to use the composer site instructions—you’re welcome to skip to the “How to Use Composer to Install Drupal” section. That said, I found it was useful to have an understanding of what the installation instructions were accomplishing, and hope that this helps you too.

First, we download the installer to the current directory.

$ php -r "copy('the-composer-website/installer-location', 'composer-setup.php');"

After downloading, we’ll verify the installer SHA-384.

$ php -r "if (hash_file('SHA384', 'composer-setup.php') === 'a-super-long-numerical-hash') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

Then we’ll run the installer.

$ php composer-setup.php

Finally, we’ll remove the installer.

$ php -r "unlink('composer-setup.php');"

Then, we’ll move the PHAR with the steps outlined below:

“You can place the Composer PHAR anywhere you wish. If you put it in a directory that is part of your PATH, you can access it globally. On unixy systems you can even make it executable and invoke it without directly using the php interpreter.After running the installer following the Download page instructions you can run this to move composer.phar to a directory that is in your path:”

$ mv composer.phar /usr/local/bin/composer

How to Use Composer to Install Drupal

Install Drupal with Composer

The composer build includes a Drush file which will make running things easier down the road. With this build, Drupal lives inside of the “web” directory.

The Drupal Composer Project on Github has a great readme about why you would install Drupal this way, and it’s the recommended method that all the DrupalCon Baltimore sessions were talking about.

$ composer create-project drupal-composer/drupal-project:8.x-dev drupal-composer-build --stability dev --no-interaction

-or- Clone Your Existing Project Down.

If someone already set up your Drupal 8 site with Composer, you can just grab what they put on your repository and recreate the configuration and modules by running Composer. I won’t cover that piece of it here, since that’s a whole ‘nother can of worms.

How to Require Drush with Composer

Okay so you’ve got your Drupal 8 site installed, but now you want to run Drush commands. With Drupal 8, there’s a new command line tool called Console which is amazing (you can even install using Composer), but maybe you just want to clear caches. The new command for that in D8 is drush cr (cache rebuild), and there are other new commands to do old familiar things.

(Recommended) Install Drush Globally (so you can run it from any project)

First, we’ll install Drush with Composer.

$ composer global require drush/drush

Then, we’ll add a Drush shim that adds a wrapper which makes dependencies a bit cleaner.

$ composer global require webflo/drush-shim

(Alternative) Site-local Drush

Using the above steps, you’ll be in a good position, but if there’s some reason you would rather have a site-local version of Drush, you can do that too! Move into your project, and then follow the site-local drush installation guide.

$ composer require drush/drush

How to Maintain a Drupal 8 Site Built with Composer

Update Drupal Core

You’ll need to follow the steps below to update your core files if you installed Drupal using the Composer build.

  1. Run composer update drupal/core –with-dependencies to update Drupal Core and its dependencies.
  2. Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or robots.txt.
  3. Commit everything all together in a single commit, so web will remain in sync with the core when checking out branches or running git bisect.
  4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as kdiff3. This setup is not necessary if your changes are simple—keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy.

Even with all of these steps, installing Drupal with Composer actually winds up taking only about an hour the first time, and only a few minutes each subsequent time. It’s nothing to fear, and it sure will keep your repositories clean! Here’s to the future of the web. *cheers*