Drupal Secure Full Version Update Guide with Composer Drush

By cc , 1 June 2026

Drupal 11.x Core Complete Update & Upgrade Tutorial

The latest recommended stable release series of Drupal is 11.2.x, while the 11.3.x series has also been officially launched, delivering what is claimed to be the biggest performance improvement in a decade – with a62% reduction in database queries, the ability to process 26%–33% more requests under the same database load, and native HTMX integration.

Whether you are currently running Drupal 11 or planning to upgrade from Drupal 10 to 11, updating via Composer and Drush is the official recommended standard method.

This tutorial covers the entire process from pre-update preparation to post-update verification.

I. Pre-Update Preparation (Mandatory Read)

1.1 Environment Requirement Verification

Drupal 11 has clear minimum version requirements for the operating environment:

PHP 8.2 or higher (PHP 8.3 is officially recommended; PHP 8.5 is supported starting from 11.3.0)
Composer 2.4 or higher
MySQL 8.0.17+ / MariaDB 10.4+ / PostgreSQL 12+
Drush 13 or higher (Drush 13 is required for full compatibility with Drupal 11)

Command to check Drush version:

drush --version

If your Drush version is lower than 13, please update Drush first.

1.2 Full Site Backup

This is the most critical step and must not be skipped.

# Backup site code (execute in project root directory)
tar -czf backup_code_$(date +%Y%m%d_%H%M%S).tar.gz .

# Backup database (via Drush)
drush sql-dump --ordered-dump --gzip --result-file=db_backup_$(date +%Y%m%d_%H%M%S).sql.gz

After backup completion, it is strongly recommended to test the update in a local or staging environment first, and then proceed with production environment updates after confirming no issues.

1.3 Enable Maintenance Mode

Always enable site maintenance mode before updating the production environment:

# Enable maintenance mode via Drush
drush state:set system.maintenance_mode 1

# Command to restore site access (execute after update completion)
# drush state:set system.maintenance_mode 0

1.4 Check Module Compatibility (Optional but Highly Recommended)

Use the Upgrade Status module to scan your site in advance and confirm all installed modules and themes are compatible with Drupal 11:

composer require 'drupal/upgrade_status:^4.0'
drush en upgrade_status -y

After installation, access /admin/reports/upgrade-status to view the full report, focusing on compatibility issues of enabled modules.

1.5 Update Contributed Modules to Latest Versions

Update all existing contributed modules and themes to their latest stable versions:

# Check for modules with available updates
composer outdated "drupal/*"

# Bulk update all contributed modules with dependencies
composer update drupal/* --with-dependencies

II. Core Update Process

2.1 Understand Version Constraints

Before starting the update, open your composer.json file and check the version constraint for drupal/core-recommended:

If the constraint is ^11 (e.g., ^11.2), it allows installation of the latest compliant versions, enabling direct updates to 11.2.x, 11.3.x and newer minor versions without modifyingcomposer.json;
If the constraint is a fixed version number (e.g., 11.1.0), you need to manually increase the version constraint.

For projects using semantic version constraints (prefixed with ^), running update commands will only update the composer.lock file while leaving composer.json unchanged. This is normal and expected behavior.

2.2 Update Drupal Core

Select the corresponding command based on your target update version:

Scenario 1: Update to the latest minor version (e.g., 11.2.x → 11.3.x)

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

Scenario 2: Specify a specific target version

# Update to Drupal 11.3
composer require 'drupal/core-recommended:^11.3' -W

This command updates both composer.json and composer.lock, ideal for scenarios where you need to explicitly define the core version constraint in project files.

Scenario 3: Upgrade from Drupal 10 to Drupal 11

If you are running Drupal 10, first ensure your site is updated to Drupal 10.3 or higher. You can either modify the core package version constraints in composer.json or run the direct upgrade command below:

composer require drupal/core-recommended:^11 drupal/core-composer-scaffold:^11 drupal/core-project-message:^11 --update-with-dependencies

composer update --dry-run

2.3 Execute Database Updates

After core code updates are completed, run Drupal's database update scripts:

drush updatedb

The system will list pending database updates and prompt for confirmation. Add the -y flag for automatic confirmation (for automated scripts):

drush updatedb -y

drush updatedb

drush cr

2.4 Import Configuration and Clear Cache

If your project uses Drupal Configuration Management, import the latest configuration changes:

# Import configuration changes
drush config:import -y

# Rebuild site cache
drush cache:rebuild

2.5 One-Click Deployment with drush deploy

For Drupal 10.3 and above (including all Drupal 11 versions), Drush provides the deploy command, which automates the full sequence of core update steps in one line:

drush deploy -y

This command automatically executes the following steps in order:

drush updatedb (database schema updates)
drush config:import (configuration import)
drush cache:rebuild (cache rebuild)
drush deploy:hook (custom deployment hooks)
drush cache:warm (cache pre-warming for Drupal 11.2+)

In most production scenarios, running drush deploy -y completes the entire update process efficiently.

III. Full Update Process Quick Reference

Below is the recommended step-by-step update workflow for production environments:

Step	Command	Description
1	`drush state:set system.maintenance_mode 1`	Enable site maintenance mode
2	`drush cr`	Clear existing site cache
3	`composer update drupal/core-recommended --with-dependencies`	Update Drupal core and dependencies
4	`drush deploy -y`	One-click execution of database updates, config import and cache rebuild
5	`drush state:set system.maintenance_mode 0`	Disable maintenance mode and restore site access
6	Visit site frontend and admin backend	Verify all site functions work properly

IV. Post-Update Verification

Complete the following verification checks after finishing the update process:

Visit the site homepage to confirm normal page loading and display;
Log in to the admin backend (/user/login) to verify full administrator functionality;
Test core features: content creation/editing, user registration, site search, menu navigation and other key workflows;
Check site status report at /admin/reports/status to confirm no system errors;
Check update report at /admin/reports/updates to confirm the correct Drupal core version is displayed.

V. Common Issues & Troubleshooting

Q1: How to fix white screen or errors after update?

First run drush cr to clear cache. If the issue persists, enable detailed error display in settings.php:

$config['system.logging']['error_level'] = 'verbose';

Then revisit the page or re-run drush updatedb to view complete error details for troubleshooting.

Q2: How to resolve Composer dependency conflicts?

Run composer update --dry-run first to check specific conflict details. Most conflicts are caused by overly strict module version constraints. Use the command below to identify modules with version constraint issues:

composer why-not drupal/core-recommended ^11

Q3: How to check the current Drupal version during updates?

# Method 1: Via Drush
drush core:status --field=drupal-version

# Method 2: Via Composer
composer show drupal/core-recommended | grep versions

Q4: What mandatory checks are required before upgrading from Drupal 10 to 11?

Before upgrading, you must complete module compatibility verification, ensure your site runs on Drupal 10.3 or higher, back up all code and database files, and conduct a full update test in a local or staging environment before deploying to production.

Conclusion

Updating Drupal core via Composer and Drush is the official community-standard method. Composer manages code-level dependency resolution, while Drush handles database migrations, configuration updates and site maintenance operations. Together, they enable efficient, reliable end-to-end update deployment.

Mastering this workflow enables you to handle routine patch updates and minor version upgrades effortlessly. It is recommended to standardize these steps into deployment scripts or integrate them into your CI/CD pipeline to achieve higher automation and operational efficiency.