Using Composer to Install Drupal and Manage Dependencies

Composer can be used to manage Drupal and all dependencies (modules, themes, libraries). Make sure you have composer installed on your local machine before executing any Composer commands.

For information on managing development dependencies read further: about installing Core's require-dev packages with Composer see the relevant section in Starting a Site Using Drupal Composer Project Templates; about npm (JavaScript) see Frontend developer tools for Drupal core.

Download Drupal core using Composer

To get the current release of Drupal, use the composer template at drupal/recommended-project. This template ensures Drupal Core dependencies are the exact same version as the latest official Drupal release. Other approaches can be found below.

For Drupal 7, use drupal-composer/drupal-project.

Create a project

For the latest stable version of Drupal:

composer create-project drupal/recommended-project my_site_name

For Drupal 7:

composer create-project drupal-composer/drupal-project:7.x-dev -n my_site_name

This will create a project in the my_site_name directory and automatically executes composer install to download the latest stable version of Drupal and all its dependencies.

The my_site_name directory will contain files that should be outside of your web root and not accessible by the web server. The web root will be the my_site_name/web directory, and typically the full path to that directory will be used as DocumentRoot (if you are using the Apache webserver).

Note that the above command will download the current official release of Drupal. If you want a different version, add the version number to the command after a colon. For example, to download version 9.3.12:

composer create-project drupal/recommended-project:9.3.12 my_site_name

All releases can be found at https://www.drupal.org/project/drupal/releases. For the latest 9.3 version, use drupal/recommended-project:^9.3 in the above command, or drupal/recommended-project:^9 for latest Drupal 9 version.

Installing with composer via docker

You might be using a docker based workflow and therefore do not have composer and its dependencies already installed. If this is the case then you can create the drupal project with this command:

docker run --rm -i --tty -v $PWD:/app composer create-project drupal/recommended-project my_site_name --ignore-platform-reqs

Install Drupal using the standard web interface

After composer finishes downloading the packages, you can navigate your browser to your site's url and start the setup. It'll ask for the database credentials, a name for the admin user and some basic information.

Install Drupal using the command line

You can use Drush to install Drupal from the command line. Add Drush in your project by running: composer require drush/drush and use drush site:install to run the command line setup wizard. Without any arguments it'll install the standard profile and ask only for database credentials.

drush site:install

To do a modified install

If you want to modify some of the properties of the downloaded composer.json before composer install is executed, use the --no-install flag when running composer create-project. For example, it is possible that you want to rename the subdirectory 'web' to something else.

To do that:

1. Run composer create-project --no-install drupal/recommended-project my_site_name
2. Change directories to my_site_name and edit the composer.json file to suit your needs. For example, to change the sub-directory from 'web' to something else, the keys to modify are the 'extra' sub-keys 'web-root' (under 'drupal-scaffold') and 'installer-paths'.
3. Run composer install to download Drupal and all its dependencies.

If you are used to building Drupal site via Drush make, refer to the FAQs in Drupal's Composer template documentation to learn the difference between this option and Drush make.

Download contributed modules, themes and their dependencies using Composer

It is increasingly common that contributed Drupal modules have dependencies to third party libraries. Some of these modules can only be installed using Composer. If you downloaded Drupal core using Composer, or if one of your modules requires Composer, you should also use Composer to download all modules and themes using Composer. Sites may encounter critical update problems if they mix Composer updates and other update methods.

This chapter has the following sub-sections:

• Download contributed modules and themes using Composer
• Define the directories to which Drupal projects should be downloaded if needed

Download contributed modules and themes using Composer

To download contributed Drupal modules or themes with composer:

• Run composer require drupal/module_name
• For example: composer require drupal/token
• This needs to be executed at the root of your Drupal install but not at the same level as the core directory.

Composer will then automatically update your composer.json, adding the module to all the other requirements in the list, like this:

{
    "require": {
        "drupal/token": "^1.5"
    }
} 

Composer will download the module and all the possible dependencies it may have.

You can enable the Drupal module in two ways:

• By using the standard Drupal web-browser interface.
• Using a command line tool like Drush or Drupal Console - see Installing Modules from the Command Line.

You can use either the project name, or the specific module name within a project when requiring modules:

• Composer will download the whole project that contains a particular module.
• For example, if you need the fe_block module from the features_extra project you can do either from the following options:
  • composer require drupal/features_extra
  • composer require drupal/fe_block

Specifying a version

You can specify the version of the module / theme you want to download as follows:

composer require 'drupal/module_name:version'

(...where version is replaced with a Composer version or version constraint.)

For example:

composer require 'drupal/token:^1.5' 
composer require 'drupal/simple_fb_connect:~3.0' 
composer require 'drupal/ctools:3.0.0-alpha26' 
composer require 'drupal/token:1.x-dev' 

To avoid problems on different terminals/shells, surround the version in quotes as in the examples above.

Note!: On Windows, the (single) quotes actually might break the version specification and lead to failure to install with 'Could not parse version constraint .....': Invalid version string "....'".

Without the quotes, e.g.:

composer require drupal/ctools:^3.7

composer require "drupal/ctools:^3.7"

it works well. See Comment 'Composer problems: "could not parse version constraint"'

In the above examples, the versions map as follows:

• ^1.5: maps to the latest stable 8.x-1.x release of the module.
• ~3.0: maps to the latest stable 8.x-3.x release of the module.
• 3.0.0-alpha26: maps to version 8.x-3.0-alpha26
• 1.x-dev: maps to 8.x-1.x-dev

For more on version constraints with ~ (tilde) and ^ (caret) see Next Significant Release Operators.

It is recommended to indicate the version of the contributed module that you want to download. In the example above, Simple FB Connect can be updated to a later version of the 8.x-3.x branch but Composer will not automatically update to 8.x-4.x if it would be released.

About semantic versioning

Drupal.org contributed projects are currently not versioned with true semantic versioning. However, the Composer service on Drupal.org translates the Contrib project version schema into a semver format that Composer can understand. This 'semver shim' will also allow Drupal.org to be flexible if the versioning standard for Contrib changes. The key element to this shim is that each major version of Drupal Core has a separate endpoint, to prevent collisions between the D7 version of a module and the D8 version

Example D7 Endpoint Version Mapping

Using Composer search

Drupal.org's composer endpoints support the Composer search function - so you can also search for Drupal projects from the command line. The format for using Composer search is:

composer search views

Using Composer browse

Drupal.org's composer endpoints support the Composer browse function - so you can find additional information about Drupal projects from the command line. The format for using Composer browse is:

composer browse drupal/token

 Check for available versions

To see which versions of Drupal core are available, use this command

composer show drupal/recommended-project --all

Result:

versions: 11.x-dev, 11.1.x-dev, 11.1.5, 11.1.4, 11.1.3, 11.1.2, 11.1.1, 11.1.0, 11.1.0-rc1, 11.1.0-beta1, 11.0.x-dev, 11.0.13, 11.0.12, 11.0.11, 11.0.10, 11.0.9, 11.0.8, 11.0.7, 11.0.6, 11.0.5, 11.0.4, 11.0.3, 11.0.2, 11.0.1, 11.0.0, 11.0.0-rc1, 11.0.0-beta1, 11.0.0-alpha1, 10.5.x-dev, 10.4.x-dev, 10.4.5, 10.4.4 [...]

Install latest release of Drupal 11

If you want to try the latest Drupal 11 release, this syntax will also get beta and rc-releases when ready, defining alpha as minimum-stability. Replace with @dev for development release:

composer create-project drupal/recommended-project:^11@alpha

See also #3276209: Install latest Drupal 10 release with Composer.

Define the directories to which modules, themes, libraries, etc. should be downloaded

If you want to change the locations in the file system where packages are installed, you can modify the "installer-paths" section of the composer.json file. This also can be useful if you need to have specific packages installed in their own locations.

This approach uses the composer/installers package and uses configuration such as this:

"extra": {
    "installer-paths": {
        "core": ["type:drupal-core"],
        "libraries/{$name}": ["type:drupal-library"],
        "modules/contrib/{$name}": ["type:drupal-module"],
        "profiles/contrib/{$name}": ["type:drupal-profile"],
        "themes/contrib/{$name}": ["type:drupal-theme"],
        "drush/{$name}": ["type:drupal-drush"],
        "modules/custom/{$name}": ["type:drupal-custom-module"],
        "themes/custom/{$name}": ["type:drupal-custom-theme"]
    }
}

Note: Custom modules and themes paths requires composer/installers package v1.0.24 and up.

In addition to the package type-based installation locations you can use vendor specific ones, like this:

"extra": {
    "installer-paths": {
        "web/libraries/ckeditor/plugins/{$name}": ["vendor:ckeditor-plugin"]
    }
}

Or package specific ones, like this:

"extra": {
    "installer-paths": {
        "web/libraries/{$name}": [ "enyo/dropzone" ]
    }
}

Note: If a particular package matches multiple installer-paths entries, the first one that matches will be used.

See the composer/installers documentation at https://github.com/composer/installers for more information on how you can use this feature.

Downloading third-party libraries using Composer

Many Drupal distributions are adopting Asset Packagist as a vehicle to download, install, and manage third-party Javascript and CSS packages into Drupal's libraries folder. Please note that Asset Packagist may not work with all imaginable third-party packages, and only supports those that have been indexed in NPM or Bower. (The Asset Packagist website provides a search mechanism to find supported packages). In general, it is not recommended to use Composer for managing dependencies in pure front-end applications, as NPM, Webpack, and Yarn are currently better suited to that task. In other words, only use Asset Packagist if your primary application is a PHP-based server-side app like Drupal, which depends on other smaller non-PHP libraries.

For Javascript dependencies that are not indexed by NPM or Bower, you may find that you can adapt this recipe on managing CKEditor plugins with Composer to your needs.

The recipe for setting up Asset Packagist for use in your projects is as follows:

1. Add the Composer Installers Extender PHP package by oomphinc to your project's root composer.json file, by running the following command:

   composer require oomphinc/composer-installers-extender

2. Add Asset Packagist to the "repositories" section of your project's root composer.json.

   "repositories": [
       {
           "type": "composer",
           "url": "https://asset-packagist.org"
       }
   ]

3. Ensure that NPM and Bower assets are registered as new "installer-types" and, in addition to type:drupal-library, they are registered in "installer-paths" to be installed into Drupal's /libraries folder, within the "extra" section of your project's root composer.json file.

   "extra": {
       "installer-types": [
           "npm-asset",
           "bower-asset"
       ],
       "installer-paths": {
           "web/libraries/{$name}": [
               "type:drupal-library",
               "type:npm-asset",
               "type:bower-asset"
           ]
       }
   }

4. The installation path of a specific library can be controlled by adding it to the "installer-paths" configuration above the general configuration. For example, the chosen module expects the library at /libraries/chosen, but composer require npm-asset/chosen-js installs the library into /libraries/chosen-js; the following override installs it into the expected folder:

   "extra": {
       "installer-paths": {
           "web/libraries/chosen": ["npm-asset/chosen-js"],
           "web/libraries/{$name}": [
               "type:drupal-library",
               "type:npm-asset",
               "type:bower-asset"
           ]
       }
   }
   

5. You may now require libraries from NPM or Bower via Composer on the command line:

   composer require bower-asset/leaflet:1.0.3

   composer require npm-asset/chosen-js:^1.8

6. Contrib and custom modules may include these dependencies in their own respective composer.json files. See Requiring third-party libraries with Composer for additional instructions.

Managing existing sites using Composer

This chapter applies to Drupal 8 sites that were originally installed without using Composer.

Download contributed modules and themes using Composer

If you initially created your Drupal website without Composer (for example by manually downloading and extracting a tarball / zip file), you will need to modify your composer.json by adding drupal.org as Composer repository and by defining the directory where modules should be downloaded.

You can use the Composerize Drupal plugin for Composer to automatically generate an updated composer.json for you. It will add contributed modules, themes, and profiles that it discovers in your existing site.

The Composerize module can "generate a composer.json from your installed Drupal code base, which can be used to regenerate that code base by running composer install."

Alternatively, you can manually modify your composer.json file. Read:

• Using packages.drupal.org (as Composer repository)
• Define the directories to which Drupal projects should be downloaded if needed

Note: You should modify the composer.json file that is at the root of your repository, not core/composer.json or the composer.json that may exist at the same level as the core directory.

See "Add Composer to existing sites" for a step by step guide to manually adding composer to existing Drupal 8 sites that were previously installed without Composer.

Updating Drupal sites using Composer

For updating a Drupal site using Composer:

• Update core via Composer
• Update modules and themes via Composer

Once Composer is used to manage a single module, it also means that Composer needs to be used to manage and update Drupal core. The reason for this is that manual Drupal core updates replace the 'vendor' directory, removing the downloaded libraries required by the contributed module.

Patching projects using Composer

You can automatically apply patches to composer-built dependencies using cweagans/composer-patches. See the project's README.md file for specific instructions.

composer require cweagans/composer-patches:~1.0 --update-with-dependencies

Note that the 2.x (master) branch of cweagans/composer-patches is the development branch and not intended for public usage. For instance patchLevel might be missing, required to patch Drupal core.

Note that patching a project's .info.yml file(s) is a little more complex, requiring a workaround.

Patching Drupal core and modules

On projects following the recommended webroot structure for core, applying core patches with cweagans/composer-patches needs to happen using the p2 patch level (i.e. to reach inside the webroot directory when the project composer.json is a level above that). Patches that simply add files can technically apply at any level, but that can mean the files get created in the wrong place. To ensure they get applied in the right place, add the following definitions to your composer.json, in the extra section, next to the patches section.

In the composer.json file change:

    "extra": {

... to this. An example core patch is included, to show the correct syntax:

    "extra": {
        "composer-exit-on-patch-failure": true,
        "patchLevel": {
            "drupal/core": "-p2",
            "drupal/contrib-module1": "-p1",
            "drupal/contrib-module2": "-p1"
        },
        "patches": {
            "drupal/core": {
                "3212792: Views button hover effect is odd": "patches/3212792-2.patch"
            }
        },

It's worth listing any contrib modules that you are patching, to explicitly use p1, to help verify that patches are applied correctly.

Since patches can change with new commits, it's recommended to download them, and use them as local files.

Note: If you have tried clearing cache, running composer update etc. and a patch just won't apply, perhaps try removing the system folders with rm -rf web/core && rm -rf web/modules/contrib && rm -rf vendor and run composer install again. For more, see Composer-Patches: The Dependency You Never Knew You Needed.

Requiring a specific commit of a module

In some cases you will need to apply a patch to a dev version of a module. In that case the patch may not apply properly if you aren't using a specific commit in the dev branch of the module. To require a specific commit, use the require format:

composer require drupal/{modulename}:{version}

For example:

composer require drupal/eck:1.x-dev#ecf376

This is usually only necessary in the case that it has been a long time since the last stable release and you need to use the dev version of a module. When doing so, drupal.org's packaging process will include package version metadata that references the number of commits since the last tag. For example, requiring drupal/eck:1.x-dev#ecf376 will include the version 8.x-1.0-alpha5+13-dev metadata within composer.lock. This version metadata represents the +13 commit since the alpha5 tag. Where possible it is recommended to use the most recent stable release along with the patches you require.

Version control with Git

If you plan to use Git to manage your Drupal site, then copy web/example.gitignore to .gitignore (The new .gitignore file should be at your project root or top-level directory. Same level as the vendor directory - outside the web directory). Review the comments in that file and edit it to suit your requirements. In most cases these steps should do it:

1. Enter project folder with cd my-project and copy the web/example.gitignore file to the root of the project:
   cp web/example.gitignore .gitignore
2. Adjust the paths from sites/ to web/sites/:
   sed -i'.bak' -z 's|\nsites|\nweb/sites|g' .gitignore
3. Remove the backup file:
   rm .gitignore.bak

The resulting file structure:
tree -La 1
├── composer.json
├── composer.lock
├── .editorconfig
├── .gitattributes
├── .gitignore
├── vendor
└── web

If you use drupal/legacy-project, then example.gitignore is in the top-level directory.

For a more detailed .gitignore file, see #3082958: Add gitignore(s) to Composer-ready project templates and the file in the MR.

Using Composer without drupal/recommended-project (advanced users)

In some cases, you may want to create your own composer project without using the drupal/recommended-project template. This could depend on your web server configuration and familiarity with using Composer.

You can create your own Composer project for your Drupal site without using the drupal/recommended-project template.

1. Run composer init inside an empty directory to initialize a new composer project.
2. Run composer require drupal/core-composer-scaffold composer/installers to install tools to help you structure and maintain your Drupal site.
3. Run composer config repositories.drupal composer https://packages.drupal.org/8 to configure composer to download modules, themes and profiles from drupal.org.
4. Modify the composer.json file to configure your preferred installation paths. It is highly recommended to use a sub-directory such as webroot, www, html, web, etc... when scaffolding your Drupal web site.
5. Run composer require drupal/core-recommended to install Drupal core into your preferred directory structure. You could also require the drupal/core package, if you did not want to lock all of Drupal core's dependencies to known-good versions.

Moving from drupal/core-recommended to drupal/core

In some cases, you may have installed Drupal using drupal/core-recommended (e.g. via drupal/recommended-project) and you want to instead depend on directly on drupal/core, for example when you need to update to a newer version of a dependency than is used in drupal/core-recommended.

Note that your Composer dependencies will no longer be locked to specific minor versions after this change, so you will need to take care to avoid accidentally updating dependencies before your site is ready.

1. Run composer remove --no-update drupal/core-recommended to remove dependency on drupal/core-recommended.
2. Run composer require --update-with-all-dependencies drupal/core to install Drupal core using drupal/core and update to latest versions allowed by drupal/core.

Note that on Drupal 9.4 and 9.5, the above commands will update your site from Guzzle 6 to 7, which may cause fatal errors with some contributed or custom code. Review the instructions for managing Guzzle updates without drupal/core-recommended.

Moving back to drupal/core-recommended from drupal/core

Depending on drupal/core is only recommended as a temporary step so that sites can depend on Guzzle 7 or other dependency versions not allowed by drupal/core-recommended's patch-level constraints. We recommend sites to move back to drupal/core-recommended when the update is addressed in core and when the site is upgraded to the latest Drupal release.

1. Run composer remove --no-update drupal/core to remove the dependency on drupal/core.
2. Run composer require --update-with-all-dependencies drupal/core-recommended to install Drupal core using drupal/core-recommended and use the latest versions allowed by drupal/core-recommended.