Acquia Developer Portal Logo

Install Drupal with Composer for your Project

  • Last updated
  • 1 minute read

Goal

Create a new Composer-managed Drupal application using Composer, install (download) a Drupal module using Composer, and update a Drupal module using Composer

Prerequisites

Overview

Learn how to create a new Drupal project using Composer with this step-by-step tutorial. Master Drupal setup and development with Composer for a streamlined workflow.

  1. Creating a new Drupal application with Composer

    Acquia recommends using Composer’s create-project command to create a new Drupal application using a predefined template.

    When you execute composer create-project [example/project], it will clone example/project from Packagist and use it as a template for your new project.

    Your new project will not depend on example/project. Think of it like photocopying the template. You’ll end up with a copy. Any future changes to the original will not affect the copy. It’s just a starting point.

    Acquia offers two such templates:

    Both of these templates follow the best practices outlined in How to Structure Your Drupal Repository.

    Try it yourself

    Using Composer

    To create a new Drupal application that uses acquia/drupal-recommended-project as a template, execute the following commands in your terminal:

    (replace drupal-project with the name of the project directory you want to use)

    composer create-project acquia/drupal-recommended-project drupal-project --no-interaction 
cd drupal-project

    For more information, see Using Composer to Install Drupal and Manage Dependencies.

    Using Acquia CLI

    If you have Acquia CLI installed on your machine (it’s already installed in all Acquia Cloud IDEs) you can alternatively use the acli new command to create a new Drupal application with Composer. The new command will simply prompt you to choose one of Acquia’s Composer templates and run the composer create-project command for you "under the hood."

    acli new drupal-project 
cd drupal-project

  2. Push your new code upstream

    Now that you have a new project, you can push your “first commit” upstream to a Git remote.  Use the typical process of adding a Git remote to your local Git repository and pushing code. E.g.,

    git init
git remote add [remote-name] [remote-url]
git push [remote-name] [branch-name]

    Where [remote-name] is whatever you’d like to name your remote (often this is origin) and [remote-url] is the remote URL of your remote Git repository. 

    For example, if you’re using Acquia Code Studio, you can find the remote URL of your Code Studio project here:

    To add this Git remote (named codestudio) and push your code, you’d run:

    git remote add codestudio [url]
git push codestudio main

    Note that the Acquia project templates configure Git to ignore Composer-provided files by default. For instance, the docroot/core directory will not be committed to your Git repository because of the following line in the .gitignore file: /docroot/core. For more information see How to Structure Your Drupal Repository. 

  3. Download a new Drupal module, theme, or distro via Composer

    All of the modules, themes, and distributions hosted on Drupal.org are made available as Composer packages. You can use Composer to download and update these packages for your Drupal application.

    First, ensure that your application follows Acquia’s best practices as defined in How to structure your Drupal repository. At minimum, your composer.json file must:

    • Include the drupal key in the repositories array so that Composer is able to locate the Drupal packages hosted on Drupal.org
    • Have a properly configured installer-paths key in order to ensure that Drupal projects are downloaded to the correct directories in your local repository

    Terminology

    Composer and Drush use the same words to mean different things. Notably, the word "install" means one thing in Composer parlance and something very different in Drupal parlance.

    TerminologyComposer MeaningDrupal & Drush Meaning
    InstallDownload to local repository and make available via Composer AutoloaderInstall to Drupal database
    PackageA Composer package, inclusive of Drupal modules, themes, distros, etc.A group of modules listed on the Drupal admin "Extend" page.
    ProjectA type of package.A module, theme, distro, or other repository hosted on Drupal.org.

    Composer allows you to "require" a set of dependencies that it "installs." Again, in Composer parlance, “install” simply means that the Composer package will be downloaded and correctly loaded (made available to PHP classes) by the Composer autoloader.

    To use Composer to "install" a new Drupal project (module, theme, profile, etc.), execute:

    composer require drupal/[project-name]

    Where [project-name] is the machine name of the project (module, theme, distro, etc.) on Drupal.org. You can always find the machine name of a Drupal project on it’s project page on Drupal.org:

    For instance, to require token, execute:

    composer require drupal/token

    This will add drupal/token to the require array in your composer.json. It will choose a default version constraint based on your composer.json configuration. E.g., if you have specified "prefer-stable": "true" then this will download the latest stable version of the package.

    You may also specify the version constraint by adding second argument:

    composer require drupal/token ^1.1.0

    Make sure to commit the changes to composer.json and composer.lock after requiring the new module. As mentioned above and in How to Structure Your Drupal Repository, the Drupal module files will not be committed to Git. Rather, Composer will read the contents of composer.lock when installing or deploying your site to another environment in order to install the expected packages.

  4. Update a single Composer package

    To update any Composer package, execute:

    composer update [org]/[package]

    For instance, to update drupal/token, execute:

    composer update drupal/token

    This will update the package within the bounds of the version constraint defined in composer.json. E.g., if composer.json defines the constraint for drupal/token as ^1.0.0, composer update will update to the latest 1.x release. It will never update drupal/token to a 2.x version. To learn more about Composer version constraints, read Versions and constraints - Composer. 

    To update drupal/token and also all of the packages that drupal/token depends on, execute:

    composer update drupal/token --with-all-dependencies

    The --with-all-dependencies option is useful not only because it updates packages which drupal/token depends on, but because the newer version of drupal/token might require newer versions of those packages. And unless you explicitly tell Composer that it’s OK to update those packages with the --with-all-dependencies option, it will give you an error saying that the new version of drupal/token is incompatible with your other already-installed packages.

    To update drupal/token and require a new version constraint (such as 1.10), execute:

    composer require drupal/token:^1.10 --update-with-all-dependencies

  5. Update all Composer packages

    To update all Composer packages (within the bounds of your version constraints), run:

    composer update

Additional Resources

Similar Tutorials