Advertising sustains the DA. Ads are hidden for members. Join today

Using Composer to Install Drupal and Manage Dependencies

Last updated on
26 January 2024

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

As of the release of Drupal 8.8.0 - the recommend composer template changed from drupal-composer/drupal-project to the officially supported: drupal/recommended-project

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

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

Create a project

For Drupal 10:

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

If you are evaluating Drupal and just want to see a site, you might try the quickstart feature. After creating the project you could type php ./web/core/scripts/drupal quick-start demo_umami and see a demo site.

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

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:

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

 or with double quotes instead of single quotes, e.g.:

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.

Using dev versions

Development releases contain changes which their maintainers have not put into a tagged release. They may not be stable, may not have an upgrade path, and any security issues that are only present in dev releases can be disclosed publicly. It is strongly recommend that you use tagged releases of modules rather than development versions, however in some cases you may find it necessary to use a dev version.

Because dev versions are pure git clones, they do not have additional version information provided by Drupal.org. This means update manager in Drupal core will not function properly for modules installed with dev versions.

To resolve this, you can install the Composer Deploy project.

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
Current Format Translated Format
{Platform.x}-{major}.{minor}-{stability#} {major}.{minor}.0-{stability}{#}
7.x-3.4-beta2 3.4.0-beta2
7.x-2.10-rc2 2.10.0-rc2
7.x-1.0-unstable3 unstable releases will not be translated, and not available to composer
7.x-1.0-alpha5 1.0.0-alpha5
7.x-0.1-rc2 0.1.0-rc2
7.x-1.x-dev 1.x-dev

Drupal.org's composer endpoints for Drupal 7 through 10 all 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 for Drupal 7 through 10 all 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

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:

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:

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.

Warning
Hotlinking to remotely hosted patches, whether on Drupal.org or another service is not recommended. A remotely hosted patch file might become inaccessible due to an outage, or even deletion, and in a worse case scenario the contents of a remotely hosted patch file can be changed which creates a risk of malicious code. 

For the integrity of your build chain, it is best practice to commit your patch files to a local repository. 

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.

Patching without updating Drupal core or modules

Sometimes you want to apply a patch to Drupal core or a contrib module, but not update anything else.

  1. Edit composer.json and add the patch
  2. Run composer install
    After composer install, sometimes the composer.lock file might not get updated with the latest patch information, so finally run this:
  3. composer update --lock

This will generate a composer.lock file from composer.json with the new patch.

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.

You should only use this as a temporary solution, until you can switch to tagged releases. The Composer team does not actively support commit references and will not accept bug reports related to it.

For this reason, composer validate will complain with this warning: pointing to a commit-ref is bad practice and can cause unforeseen issues.

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.

Using drupal/recommended-project Without drupal/recommended-project
Installs only in a "web" sub-directory Installs in your preferred installation path e.g. webroot, www, html, public_html, app, etc...
Configures Composer usage without manually modifying JSON. Installs only what you want to install.

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.

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.

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 Drupal 10.

  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.

Help improve this page

Page status: No known problems

You can: