Drupal Upgrade Status Module: Check If Your Site Is Ready

The Upgrade Status module tells you, before you change any code, what stops your Drupal site from moving to the next major version. Install it on a development copy, run the scan from Reports → Upgrade status or with drush upgrade_status:analyze --all, and it sorts every module and theme into a clear next step: remove, update, fix or nothing to do. Use the 4.3.x branch on a Drupal 10 site that is heading for Drupal 11, and the 5.x branch when you are preparing a Drupal 11 site for Drupal 12.

Key takeaways

• Upgrade Status checks your Drupal version, your server against the next major version's requirements, your contributed projects and your custom code.
• Run it on the version you have now. Most checks cannot run after the upgrade, because the deprecated code they look for is gone.
• Pick the branch by target: 4.3.x (Drupal 9, 10 and 11) for a move to Drupal 11, and 5.x (Drupal 10.4, 11 and 12) for a move to Drupal 12. At the time of writing, 5.x is still an alpha release.
• The report groups everything into next steps, so you can tell in minutes whether you face a few days of updates or weeks of custom work.
• Upgrade Status finds problems but does not fix them. Drupal Rector fixes many deprecations in custom code automatically.

What the Upgrade Status module checks

Upgrade Status reviews the environment and every component of your site against the next Drupal major version. According to the project page on drupal.org, it covers five areas:

1. Your Drupal version. It checks that you are on a release that supports an upgrade. A Drupal 10 site must be on 10.3 or later before it can move to Drupal 11.
2. Your server. It compares PHP, the database and other system components with the next major version's requirements.
3. Contributed projects. Through the core Update Status module, it shows which modules and themes have a newer release you should install first.
4. Compatibility problems in code. It runs PHPStan and other checks to find deprecated PHP APIs, deprecated Twig, deprecated libraries and deprecated configuration keys, and it checks each project's .info.yml and composer.json.
5. Command line and CI use. Drush commands let you run the same scan in a terminal or a pipeline.

If your deadline is the end of Drupal 10, this report is the first practical step. We cover the dates and the full upgrade plan in Drupal 10 end of life: what happens and what to do now.

Which Upgrade Status version to install

Install the branch that supports the version you are on now and the version you are moving to. Upgrade Status always checks readiness for the next major version, so a Drupal 10 site gets a Drupal 11 report and a Drupal 11 site gets a Drupal 12 report.

The 5.x branch is where the Drupal 12 work happens: its latest release notes mention improved Drupal 11.4 and 12.0 compatibility and more known Rector coverage. Because it is an alpha, it is not covered by the Drupal security advisory policy, which applies to stable releases only. That is one more reason to keep it on a development copy and off production.

Last checked against the Upgrade Status project page on drupal.org: 12 November 2026.

How to install Upgrade Status

Install Upgrade Status with Composer on a development or staging copy of the site. The module depends on third-party PHP libraries, so a manual download will not work. The project page recommends the following order.

1. Remove Drush temporarily, to avoid dependency conflicts:

   composer remove drush/drush

2. Install Drupal's developer dependencies at the same version as your core. Without them, scanned test code produces false errors:

   composer show drupal/core | grep versions
   composer require --dev drupal/core-dev:[your core version] --update-with-all-dependencies

3. Add Upgrade Status, using the constraint from the table above:

   composer require 'drupal/upgrade_status:^4.3'

4. Add Drush back:

   composer require drush/drush

5. Enable the module:

   drush en upgrade_status -y

On a Drupal 11 site preparing for Drupal 12, replace step 3 with composer require 'drupal/upgrade_status:^5.0@alpha'.

How to run the scan

You can run the scan in the browser or with Drush. Both produce the same results.

In the admin interface

Go to Administration → Reports → Upgrade status. Select the projects you want to check, or all of them, and start the scan. The first scan of a large site can take a while, because each project is analysed with PHPStan.

With Drush

The upgrade_status:analyze command (alias us-a) scans projects and prints or exports the results. The module must be enabled for the command to work. These are the commands we use most:

# Scan everything that is installed
drush upgrade_status:analyze --all --ignore-uninstalled

# Scan only your own code
drush us-a --all --ignore-contrib

# Scan named projects
drush us-a webform my_custom_module

# Export for GitLab CI (Code Climate JSON)
drush us-a --all --format=codeclimate > upgrade-status.json

Other options include --ignore-custom, --ignore-list for a comma-separated list of projects to skip, --skip-existing to reuse earlier results and --phpstan-memory-limit when PHPStan runs out of memory. Output formats are plain, checkstyle (XML) and codeclimate (JSON).

How to read the Upgrade Status report

Read the summary first. Upgrade Status puts every project into one of seven groups, and each group tells you the next action. The labels below come from the module's own code.

The report also has an environment section. It lists the checks for your Drupal version, PHP version, database and other requirements. Fix those early: a hosting change usually takes longer than any code change. For Drupal 11 you need PHP 8.3 or later. Drupal 12 will require PHP 8.5, MariaDB 10.11 or PostgreSQL 18 as minimum database versions (MySQL 8.0 and SQLite 3.45 stay the same as for Drupal 11).

Inside each project, problems are marked as errors or warnings. Errors block the upgrade. Warnings point to things that will become errors later or that need a closer look.

How to fix what the report finds

Work through the groups in this order: environment, then Remove, then Update, then custom code, then the contributed projects that still need help. Each step makes the next scan shorter.

Core modules removed in the next version

Upgrade Status flags core modules that the next major version no longer includes. Before the upgrade, either stop using them or install their contributed versions.

The Drupal 12 list comes from the drupal.org upgrade guide, which is still marked as work in progress before the Drupal 12 release. Migrate Drupal and Migrate Drupal UI have no contributed replacement listed in that guide.

Custom code: Drupal Rector first

Upgrade Status finds deprecated API use but does not change your code. Drupal Rector does. Install it as a development dependency, copy its configuration and run it on your custom code with a dry run first:

composer require --dev palantirnet/drupal-rector
cp vendor/palantirnet/drupal-rector/rector.php .
vendor/bin/rector process web/modules/custom --dry-run

Review the proposed changes, run it without --dry-run, then scan again with Upgrade Status. Whatever is left in "Fix manually" needs a developer.

Contributed modules without a compatible release

For contributed projects in "Collaborate with maintainers", the drupal.org upgrade guide suggests three routes:

• Check the issue queue for a compatibility patch, and apply it with the Drupal Lenient Composer endpoint if the module's version constraint still blocks Composer.
• Allow two major versions in composer.json to bridge the gap, for example "drupal/linkit": "^6.1 || ^7.0".
• Check by hand. The guide says Upgrade Status is helpful but not perfect, so a compatible release can exist even when the report does not show it. composer why-not drupal/core ^11 names the packages that still block the upgrade.

Common mistakes with Upgrade Status

• Scanning after the upgrade. The project page is clear: run compatibility checks on your current site against the next version. On an upgraded site, the deprecated APIs are no longer there to detect.
• Trying to skip a version. Neither Upgrade Status nor Drupal core supports jumping two major versions. A Drupal 10 site goes to 11 first, then to 12.
• Running it on production. The scan is heavy, the install changes your Composer dependencies, and the 5.x branch is an alpha. Use a development or staging copy.
• Scanning without drupal/core-dev. You get false errors from test code and lose time on problems that are not real.
• Trusting a single green report. A clean scan means the code checks pass. It does not test your integrations, editorial workflows or theme. Those still need a test round on staging.

From report to upgrade estimate

The report is the most reliable input for an upgrade estimate, because it replaces guesses with a list. In our experience, three numbers say most of what you need to know: how many projects are in "Fix manually", how many contributed projects are in "Collaborate with maintainers", and whether the environment checks pass. A site with only Update items and a compatible server is usually a short job. A site with custom modules to fix by hand and contributed modules waiting for patches needs a plan, a staging environment and time for testing.

Once the report is clean, the drupal.org guide suggests uninstalling and removing the module before you run the core upgrade itself:

drush pm:uninstall upgrade_status -y
composer remove drupal/upgrade_status --no-update

Frequently asked questions

Do I need to uninstall Upgrade Status before upgrading Drupal?

It is recommended, though the drupal.org guide lists it as an optional clean-up step. Once the report shows your site is compatible, uninstall the module and remove it with Composer, then run the core upgrade. Reinstall the matching branch later when you prepare for the following major version.

What is the difference between Upgrade Status and drupal-check?

drupal-check is a command line tool that finds deprecated PHP code and can run without a Drupal site. Upgrade Status is built on the same internals but runs inside a site, so it also checks Twig, libraries, .info.yml, composer.json, configuration, the next version's system requirements and available project updates, and it has a web report. Use drupal-check for quick checks of a single codebase; use Upgrade Status to plan a site upgrade.

Can I install Upgrade Status on an existing live site?

You can, but you should not. Install it on a copy of the live site with the same code and database. You get the same report without changing production dependencies or putting the load of a full PHPStan scan on the live server.

Need help with your Drupal upgrade?

DevAtWork is a Drupal agency in Bucharest, Romania. We upgrade, migrate and maintain Drupal sites for organisations and digital agencies across Europe. If you have an Upgrade Status report and want to know what it means for your timeline and budget, see our Drupal migration and upgrade services or tell us about your site. For sites that need to stay current after the upgrade, our Drupal maintenance and support covers monthly and security updates.

Sources

• Upgrade Status project page (drupal.org)
• Upgrade Status 5.0.0-alpha3 release notes (drupal.org)
• Upgrade Status source code, report groups (git.drupalcode.org)
• How to upgrade from Drupal 10 to Drupal 11 (drupal.org)
• How to upgrade from Drupal 11 to Drupal 12 (drupal.org)
• Announcing Drupal 12.0.0 platform requirements (drupal.org)
• Drupal Rector (drupal.org)