Updating your Drupal site is a critical task to ensure security, performance, and compatibility. With tools like Composer and Drush, the process becomes streamlined, especially when you want to stay within the same branch (e.g., updating from Drupal 10.4.x to 10.4.y).

In this tutorial, we’ll walk you through the step-by-step process of updating Drupal core, contributed modules, and themes using Composer and Drush, all while keeping everything in the same branch. Whether you're a seasoned developer or a Drupal newbie, this guide has you covered!

Prerequisites

Before we start, make sure you have the following set up:

1. A Drupal site managed by Composer: Your site should have a composer.json file in the root directory.
2. Drush installed: Drush is a command-line tool for managing Drupal. You can install it globally or as a Composer dependency in your project.
3. Git (optional but recommended): For version control and backups.
4. Access to the terminal: You’ll need to run Composer and Drush commands.
5. A backup of your site: Always back up your database and files before performing updates.

Got everything ready? Great! Let’s move on.

Step 1: Check Your Current Versions

First, let’s see what we’re working with. Open your terminal, navigate to your Drupal project’s root directory, and run:

composer outdated "drupal/*"

This command lists all outdated Drupal packages (core, modules, and themes) managed by Composer. You’ll see something like this:

drupal/core           10.3.5  10.4.4  Drupal core
drupal/pathauto       1.11  1.13  Generates URL aliases
drupal/token          1.10  1.15  Provides token functionality

Next, check your Drush version to ensure compatibility:

drush --version

You should see output like Drush Commandline Tool 12.5.3.0 If Drush is outdated, update it with:

composer update drush/drush

Step 2: Back Up Your Site

Before making any changes, back up your database and files. Use Drush to export your database:

drush sql-dump > backup.sql

Copy your site files (including web/ and vendor/) to a safe location or commit your changes to Git:

git add .
git commit -m "Pre-update backup"

Safety first!

Step 3: Update Drupal Core

To update Drupal core within the same branch (e.g., 10.3.x to 10.3.y), you have a few options depending on your setup. Here are three methods inspired by the official Drupal release notes (like those for Drupal 10.4.4), tailored for Composer-managed sites:

Option 1: Update with Composer (Recommended)

This is the standard approach for Composer-managed sites. Open your composer.json file and check the version of Drupal core under "require":

"drupal/core": "^10.3"

The ^10.3 constraint ensures Composer updates to the latest 10.3.x release without jumping to 10.4.x. 

Run:

composer update drupal/core --with-dependencies

This updates Drupal core and its dependencies (e.g., Symfony components) to the latest compatible version, such as 10.3.5. Check the output to confirm the update.

Option 2: Specify a Specific Version

If you need a specific version (e.g., 10.4.4 instead of the latest in the branch), modify composer.json to pin the version:

"drupal/core": "10.4.4"

Then run:

composer update drupal/core --with-dependencies

Alternatively, you can update directly from the command line without editing composer.json:

composer require drupal/core:10.4.4 --update-with-dependencies

This ensures you get exactly 10.4.4, which is useful for testing or aligning with a specific release.

Option 3: Manual Update with Composer Packages

For more control (or if you’re troubleshooting), you can use the separate Composer packages recommended by Drupal.org (drupal/core-recommended or drupal/core-dev). First, adjust your composer.json to use:

"drupal/core-recommended": "^10.4"

Then run:

composer update drupal/core-recommended --with-dependencies

The core-recommended package includes Drupal core plus a set of pinned dependencies for stability. This mimics the approach in Drupal’s release notes for manual tarball updates but leverages Composer’s dependency management.
 

Note: Stick with your existing setup unless you have a reason to switch (e.g., drupal/core vs. drupal/core-recommended). 

For this tutorial, Option 1 is the simplest for staying in-branch.

Step 4: Update Contributed Modules

Now, let’s update your contributed modules. To stay in the same branch (e.g., 1.x for a module), ensure your composer.json specifies compatible versions. For example:

"drupal/pathauto": "^1.11",
"drupal/token": "^1.10"

Run:

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

Or, to update all contributed modules at once:

composer update "drupal/*" --with-dependencies

Composer will fetch the latest versions within the specified branches. Check the output to confirm the updates.

Step 5: Update Themes

Themes follow a similar process. If you’re using a contributed theme like drupal/olivero, check its version in composer.json:

"drupal/olivero": "^1.0"

Update it with:

composer update drupal/olivero --with-dependencies

Alternatively, if you used composer update -W in Step 4, your themes would already be updated along with modules, assuming no conflicts. For custom themes not managed by Composer, you’ll need to update them manually or via Git (if they’re in a repository).

Step 6: Run Database Updates with Drush

After updating files, Drupal might need to apply database updates. Use Drush to do this:

drush updatedb

This runs any pending update hooks (e.g., hook_update_N()) from core or modules. You’ll see output like:

[success] No database updates required.

Or, if updates are applied:

[success] Applied update 10101 for module 'pathauto'

Step 7: Clear the Cache

Clear Drupal’s cache to ensure the updates take effect:

drush cache:rebuild

This command rebuilds the cache and ensures your site reflects the latest changes.

Step 8: Test Your Site

Visit your site in a browser and test key functionality:

• Navigate pages to check for errors.
• Test updated modules (e.g., create a Pathauto alias if you updated it).
• Verify your theme renders correctly.

If you encounter issues, check the logs with Drush:

drush watchdog:show

Step 9: Commit Your Changes

If everything works, commit your updated composer.json and composer.lock files to Git:

git add composer.json composer.lock
git commit -m "Updated Drupal core, modules, and themes"

Troubleshooting Tips

• Composer conflicts: If you see dependency conflicts, run composer why-not drupal/core 10.4.4 to diagnose.
• Drush errors: Ensure Drush is compatible with your Drupal version (e.g., Drush 12 for Drupal 10).
• Permission issues: Adjust file permissions if Composer or Drush fails to write files.

Updating Drupal core, contributed modules, and themes within the same branch using Composer and Drush is straightforward once you get the hang of it. By following this process—checking versions, backing up, updating with Composer, and finalizing with Drush—you’ll keep your site secure and up-to-date without breaking compatibility.

Have questions or run into a snag? Drop a comment below, and we’ll help you out. 

Happy updating!