Complete guide to using Composer with Drupal

By Nacho Morato, 9 June, 2025

If you work with websites built in Drupal, you have surely heard about Composer. This tool has become essential for managing PHP projects, especially for those who want to keep their dependencies up to date and their code organised. In Drupal’s case, Composer is not only useful—it is now the recommended way to install and maintain the core, modules, themes, and other libraries.

In this article we explain in full detail how to use Composer with Drupal, from installation to handling updates, creating new projects, and resolving conflicts. Whether you are just starting out or want to reinforce your knowledge, here is a comprehensive guide with everything you need to know.

What is Composer and why is it essential for Drupal projects?

Composer is a dependency manager for PHP that allows you to declare your project’s libraries and installs them automatically along with their corresponding versions. In the Drupal ecosystem, Composer has been adopted as the standard way to install the core, modules, and themes, replacing the manual methods of the past.

The great advantage is that Composer resolves dependencies between projects, preventing conflicts and enabling controlled updates. It also manages a composer.lock file that ensures every environment runs on the exact same version of each package.

Installing Composer on your system

Before working with Composer, you need to install it on your operating system. You can do so by following the steps on its official website at getcomposer.org. Once installed, verify that it is working correctly by running the command:

composer --version

If you get a response with the version number, Composer is ready to use. You can also simply type composer to see the list of available commands.

Creating a new Drupal project using Composer

An efficient and recommended way to start a new Drupal site is to use a base project via Composer. The most popular one right now is drupal/recommended-project.

To start a new project, just run the following command:

composer create-project drupal/recommended-project project-name

This command will create a new folder with that name, download Drupal core, and set up the recommended structure to keep your code organised.

If you want to use a specific Drupal version, you can specify it like this:

composer create-project drupal/recommended-project:^10.0 project-name

Configuring the composer.json file

The composer.json file is the heart of your project. It declares all the dependencies your site needs and how they should be installed. It is vital that it contains appropriate configurations such as:

The Drupal.org repository in the repositories array
The installer-paths key to define where modules, themes, and profiles should be placed

This file can also include metadata such as the project name, version, licence, and description. When you add dependencies, Composer automatically updates this file along with composer.lock.

Installing modules or themes with Composer

To install a new module, you just need to know its machine name on Drupal.org and use:

composer require drupal/module_name

This command will download the module and its dependencies automatically. For example, to install Token:

composer require drupal/token

You can also specify the version:

composer require drupal/token:^1.1.0

Updating modules and themes with Composer

To keep your modules up to date, Composer makes the process much easier. You only need to run:

composer update drupal/module_name

If you want to update the module’s dependencies as well, add --with-all-dependencies:

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

If you need to enforce a minimum version for Drupal core:

composer require drupal/core:^10.0 --update-with-all-dependencies

To update the entire project according to version constraints:

composer update

Converting an existing project to use Composer

If you have a Drupal site without Composer and want to migrate it, there are tools such as:

The Composerize plugin for Drupal
The Composerize module

If these options do not work for you, you can do it manually by creating a composer.json from scratch, adding dependencies one by one, and installing them with composer install.

Using Upgrade Status and Drupal Check before a major update

When upgrading to major versions like Drupal 10, it is best to use tools that analyse compatibility. Two of the most recommended are:

Upgrade Status: scans your installation and shows you incompatible modules, deprecated functions, errors in .info.yml and composer.json files
Drupal Check: a static-analysis tool that identifies deprecated or incompatible function calls

You can install Upgrade Status with Composer like this:

composer require drupal/upgrade_status:4.x-dev --dev

And Drupal Check:

composer require mglaman/drupal-check
php vendor/bin/drupal-check

Managing PHP versions

Drupal 10 requires PHP 8.1 at minimum. You can ensure your project enforces this by adding:

composer require php:"^8.1" --no-update

You can also set the platform version to simulate a specific environment:

composer config platform.php 8.1

This is useful in continuous-integration environments or on local machines with different versions.

Resolving conflicts when updating Drupal core

During a major update (e.g. from Drupal 9 to 10), Composer may detect incompatibilities between dependencies. Composer will display an analysis listing the conflicting packages.

For instance, an incompatibility with Devel could be resolved like this:

composer require drupal/devel:^5.0 --no-update
composer update

Repeat this process for each conflict that appears until the update is complete. It may involve using development versions or even applying patches from Drupal.org.

Autoloading and project structure

Composer automatically generates an autoload.php file that you can require in your code to include all installed libraries. For example, in an index.php file you might use:

require 'vendor/autoload.php';

This is very handy when working with libraries like Kint for debugging:

d($variable);

Additionally, Composer automatically organises your dependencies in the vendor folder and keeps your repository clean, since you do not need to commit the modules manually.

Removing dependencies

Want to remove a library or module? Simply delete it from the require block in composer.json and then run: