The Drupal Composer workflow manages core, contributed modules, patches, and updates as versioned PHP dependencies. New sites start from the official project template, then add and update code with Composer commands rather than manual downloads. Composer is the PHP dependency manager that installs and updates that code. This workflow covers Drupal 10 and 11 sites built with Composer, from setup through everyday updates.
Table of Contents
- Start from the official template
- Add modules and libraries as dependencies
- How do you run core and module updates?
- How do you handle patches and automatic updates?
Start from the official template
New Drupal sites should start with `composer create-project drupal/recommended-project my_site_name`. According to Drupal.org's Using Composer to Install Drupal and Manage Dependencies, this template has been the officially supported starting point since Drupal 8.8.0.
It replaced `drupal-composer/drupal-project`. Starting from the current template gives you the expected folder layout, core packages, and update path.
Add modules and libraries as dependencies
Composer treats core, contributed modules, themes, and third-party libraries as versioned packages. Site builders add code with `composer require drupal/MODULE_NAME`, for example `composer require drupal/geofield`.
This approach records the exact version in `composer.json` and `composer.lock`. It also pulls compatible dependencies automatically, which avoids mismatched manual downloads.
How do you run core and module updates?
Site owners apply minor and patch core updates with `composer update "drupal/core-*" –with-all-dependencies`, then run database updates and test. Drupal.org describes this command in Updating Drupal core via Composer as the standard path for Composer-built sites. Update contributed modules individually when possible.
The Drupal.org User Guide recommends `composer update drupal/geofield –with-dependencies`, substituting the target project name. The `drupal/core-recommended` metapackage favors stability by holding most dependencies to patch-level updates. Minor or major dependency changes require explicitly updating that metapackage, as Drupal.org notes in its core update guide.
- Run updates locally or in development first, not directly on live.
- Review the proposed version changes before accepting them.
- Run database updates after the code update.
- Test key pages, forms, login, and payment paths before deploy.
How do you handle patches and automatic updates?
Teams apply core and contributed patches through the community-standard `cweagans/composer-patches` plugin. Install it with `composer require cweagans/composer-patches:~2.0`, then declare patch URLs under `extra.patches` in `composer.json`, as documented by Drupal.org and the composer-patches plugin source. For automated patch handling, Drupal.org offers the Automatic Updates module.
It must be added with `composer require drupal/automatic_updates:^3` and requires Composer 2.6 or later. Composer-managed filesystems cannot be updated through the Drupal admin UI. Teams must run Composer updates locally, commit the resulting `composer.lock`, deploy, then run `update.php` or `drush updatedb`.
