Editorial Drupal update workflow showing status check, Composer lock file, staging tests, deployment and anonymous-site verification

Editorial illustration; commands are examples and must be adapted to the site’s Composer project.

“Update Drupal” sounds like one task, but a safe core update is a chain: identify the project, check what can change, preserve a recovery path, test the result, deploy the lock file and run the required database updates. Skipping one link can leave Composer, the code on disk and Drupal’s status report disagreeing about the version.

This guide is for a Composer-managed Drupal site receiving a minor or patch-level core update within its supported major-version process. It is not a major-version upgrade guide, and it is not a command to paste into an unknown production site.

Summary

  • Check the project and supported version before changing composer.json or composer.lock.
  • Back up files and the database, update a local or staging copy first, and test the site’s important journeys.
  • Deploy the tested lock file, use composer install --no-dev on production, run database updates and rebuild caches where required.
  • Treat a mismatch between Composer and Drupal’s status report as a problem to investigate, not a harmless display glitch.

Patch update or major upgrade?

A patch update stays within the site’s current supported minor line. A minor update may bring broader dependency or compatibility changes. A major-version upgrade needs a dedicated plan, contributed-module review and migration work; do not use this article’s routine patch workflow as a shortcut.

Start in the project’s composer.json and confirm whether it uses drupal/core-recommended or drupal/core. The package choice affects the dependency constraints and the command you should run. Drupal’s official documentation recommends Composer for Composer-managed sites and separates core updates from major upgrades.

1. Inspect before you update

From a local copy of the project, inspect the current status and available updates:

composer show drupal/core
composer outdated "drupal/*"
composer audit

Review Drupal’s release notes and security advisories for the target version. Check the site’s status report and resolve existing errors where practical. An update is a poor time to discover that the current site already has a broken deployment, missing PHP extension or unsupported module.

Record the current commit, Drupal version, PHP version, Drush version and database engine. This note turns a future failure into a comparison instead of a memory test.

2. Confirm recovery options

Back up the database and the files required to recreate the site. Keep the backup outside the live release directory and, for important sites, verify that a restore can be performed. A Composer lock file can reproduce dependencies; it cannot replace content, uploaded files or a database backup.

Check whether the deployment process expects configuration exports, generated files or a particular release directory. If the site has custom patches, document them before updating. Do not remove custom changes just to make Composer finish without understanding their purpose.

3. Update the local project

For a project using drupal/core-recommended, Drupal’s documented pattern for a core update is commonly:

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

For a project using drupal/core rather than the recommended package, the dependency command differs. Use the project’s documented package set and review the proposed changes before accepting them. Run Composer from the project root and keep the resulting composer.json and composer.lock together.

Do not run composer update directly on production as a substitute for a tested deployment. It can resolve a different dependency graph from the one tested locally and make the release difficult to reproduce.

4. Read the dependency change

Inspect the diff. Look for changes to Drupal core, Symfony or other shared packages, contributed modules and the PHP platform requirement. A dependency update is not automatically wrong, but every extra change expands the test surface.

If Composer refuses the target, use its conflict information to identify the blocker. Do not force a version constraint just to make the command complete. A contributed module that has not declared compatibility may need an update, a patch, or a deliberate decision to stay on the current core line.

5. Run the site’s real tests

On local or staging, apply the updated dependencies and run the checks that match the site:

  1. Open the homepage and a representative content page as an anonymous visitor.
  2. Log in with an editor role and create, preview and save a disposable draft.
  3. Test media upload, search, forms, translations, moderation and any integration the site depends on.
  4. Review the status report and recent logs.
  5. Run automated tests or a smoke-test script if the project has one.

Do not consider an administrator page loading as proof that the public site is healthy. The recent Drupal Content Translation: Plan the Fields Before You Translate guide is a reminder that field and language workflows deserve a real test when they matter to the site.

6. Apply database updates deliberately

Some updates require database changes. Follow the release and project instructions, then run the database update procedure through Drush or the documented web route. Rebuild caches after the update when the workflow requires it.

The usual commands on a Drush-managed project are often:

drush updatedb
drush cache:rebuild

The exact command, permissions and maintenance-mode handling depend on the site. Record the output and do not hide a failed update by clearing the screen or running the command repeatedly without reading the error.

7. Deploy the tested lock file

Once staging works, commit the intended Composer changes and deploy them through the normal release process. On production, install the exact dependency set from the lock file, commonly with:

composer install --no-dev

This is different from resolving fresh versions on the server. Confirm that the production PHP version, extensions, file permissions and environment variables match the tested assumptions.

Run database updates and cache rebuilds in the documented order. If configuration management is part of the project, follow the project’s export/import rules and review any configuration changes created by the update.

8. Verify code, status and visitor paths

After deployment, check the version in the status report, the release identifier, the homepage, representative content, login, editor actions, forms and integrations. Test as an anonymous user as well as an administrator.

If Composer reports a new core version but Drupal still reports the old version, stop treating it as cosmetic. Drupal’s documentation describes cases where the code on disk and the Composer result diverge. Inspect the release directory, deployment output and core/lib/Drupal.php only as a diagnostic step, then repair the deployment from a known-good lock file rather than editing generated core files by hand.

What not to do

  • Run a major-version upgrade during a routine patch window.
  • Update production with a fresh dependency resolution that was never tested.
  • Delete vendor or web/core without a documented recovery plan.
  • Skip the database update because the homepage appears normal.
  • Declare success without an anonymous visitor check and a status-report review.

My Take

Composer makes Drupal updates more reproducible, but reproducibility is a process, not a magic command. The important artefact is the tested lock file paired with a backup, a release note and a short verification record. If a site cannot explain how those pieces travel together, the next improvement is the deployment workflow rather than a more aggressive update command.

Conclusion

Identify the update scope, inspect the project, back up the site, update and test locally, deploy the lock file, run required database work and verify the public site. Keep patch maintenance separate from major upgrades. A small, repeatable release note is part of the update itself.

Sources