Upgrade Status
Review Drupal major upgrade readiness of the environment and components of the site by scanning code for deprecated API usage.
upgrade_status
Install
composer require 'drupal/upgrade_status:^4.3'
Overview
Upgrade Status is a comprehensive developer tool that scans your Drupal site's codebase to identify compatibility issues with the next major Drupal version. It analyzes installed contributed and custom modules, themes, and profiles to detect deprecated code that must be replaced before upgrading.
The module uses PHPStan with the mglaman/phpstan-drupal extension to perform static code analysis, along with specialized analyzers for Twig templates, CSS selectors, library definitions, routing files, theme functions, and extension metadata. Results are categorized by severity and actionable next steps, helping developers prioritize their upgrade work.
Upgrade Status integrates with Drupal's Update module to show available updates for contributed projects and indicates whether those updates are compatible with the next major Drupal version. It supports exports in HTML and ASCII formats for sharing reports with stakeholders, and provides Drush commands for CI/CD integration.
Features
- Performs PHPStan-based static code analysis to detect deprecated PHP API usage in modules, themes, and profiles
- Analyzes Twig templates for deprecated syntax and filters (such as the spaceless tag)
- Scans CSS files for deprecated selectors (e.g., #drupal-off-canvas)
- Checks library definitions (*.libraries.yml) for deprecated library dependencies
- Validates routing files for deprecated route requirements (e.g., _access_node_revision, _access_media_revision)
- Detects deprecated theme function usage and overrides (removed in Drupal 9/10)
- Validates extension metadata (*.info.yml) for missing or incompatible core_version_requirement
- Checks Views configuration for deprecated settings (e.g., default_argument_skip_url)
- Provides environment compatibility checks for Drupal 10, 11, and 12 including PHP version, database type/version, JSON support, and Drush version
- Categorizes projects by recommended next steps: Remove uninstalled, Update available, Scan needed, Collaborate with maintainers, Fix with rector, Fix manually, or Compatible
- Distinguishes between custom and contributed projects based on directory structure or composer/git deploy metadata
- Integrates with Update module to display available project updates and next major version compatibility
- Shows a visual progress indicator showing percentage of site readiness for upgrade
- Exports scan results as downloadable HTML or ASCII text files
- Provides modal dialog view of detailed scan results per project
- Supports batch processing with HTTP sandboxing to handle PHP fatal errors gracefully
- Includes Drush commands for command-line analysis and CI/CD integration with multiple output formats (plain, checkstyle XML, Code Climate JSON)
- Categorizes deprecations as 'fix now', 'fix later', 'can be fixed with rector', or 'ignore' based on version and removal timeline
- Detects deprecations covered by drupal-rector for automated fixes
Use Cases
Preparing for Drupal 10 to 11 Upgrade
Before upgrading from Drupal 10 to 11, navigate to Administration > Reports > Upgrade status. First review the environment checks to ensure your hosting meets D11 requirements (PHP 8.3+, MySQL 8.0+/MariaDB 10.6+/PostgreSQL 16+, Drush 13+). Then select all projects and click 'Scan selected' to analyze your codebase. Review the categorized results: update any projects with available updates first, then address deprecations in custom code. Projects marked 'Fix with rector' can use drupal-rector for automated fixes. Export results as HTML to share with your team or stakeholders.
Continuous Integration Deprecation Checking
Add Upgrade Status scanning to your CI/CD pipeline using Drush commands. Run 'drush upgrade_status:analyze --all --ignore-uninstalled --format=codeclimate > gl-code-quality-report.json' to generate a Code Climate compatible report for GitLab CI. For Jenkins or other CI systems, use '--format=checkstyle' to generate XML output compatible with static analysis tools. Set the command to fail (exit code > 0) when deprecations are found to block merges that introduce deprecated API usage.
Auditing Contributed Module Compatibility
When evaluating contributed modules for a new project, use Upgrade Status to check their compatibility with future Drupal versions. Install the candidate modules, run a scan, and review which modules are already compatible, which need updates, and which require collaboration with maintainers. This helps prioritize module selection and identify potential upgrade blockers early in project planning.
Identifying Rector-Fixable Deprecations
For large codebases with many deprecations, use Upgrade Status to identify which issues can be automatically fixed. Projects categorized as 'Fix with rector' contain deprecations covered by drupal-rector rules. Run 'drush upgrade_status:analyze mycustommodule' to scan your module, then install drupal/rector and run 'vendor/bin/rector process web/modules/custom/mycustommodule' to automatically apply fixes. Re-scan to verify the fixes were applied correctly.
Generating Stakeholder Reports
Generate professional reports for project managers or clients by selecting all projects and clicking 'Export selected as HTML'. The exported HTML file contains a complete summary of all deprecations organized by project type (custom vs contributed), with clear categorization of fix urgency. For technical teams preferring terminal output, use 'Export selected as text' for an ASCII report that can be included in emails or documentation.
Tips
- Start upgrade preparation early by running Upgrade Status on your current Drupal version, even if you're not ready to upgrade yet
- Focus on fixing 'now' category deprecations first - these are removed in the immediate next major version
- Update contributed modules before scanning - newer versions often contain deprecation fixes
- Use the Drush command with --skip-existing to reuse cached results when iterating on fixes
- The 'Fix with rector' category indicates drupal-rector can automate fixes - consider using it for large codebases
- Check the 'Collaborate with maintainers' category for drupal.org issues and patches you can contribute to
- Export reports before and after fixing deprecations to track progress and demonstrate work completed
- For accurate environment checks, ensure you're running the same PHP version and database as your production environment
Technical Details
Admin Pages 2
/admin/reports/upgrade-status
The main upgrade status report page that displays comprehensive information about your site's readiness for the next major Drupal version. The page dynamically shows 'Drupal 10 upgrade status', 'Drupal 11 upgrade status', or 'Drupal 12 upgrade status' depending on your current Drupal version.
/admin/reports/upgrade-status/project/{project_machine_name}
Displays detailed scan results for a single project in a modal dialog. Shows all detected deprecations organized by category with file paths, line numbers, and suggested fixes.
Permissions 1
Hooks 2
hook_upgrade_status_operations_alter
Allows modules to alter the batch operations run when scanning projects. Useful for adding additional processing like running rector.
hook_upgrade_status_result_alter
Allows modules to alter the rendered result display for a specific project and result group. Useful for adding custom information or modifying descriptions.
Drush Commands 2
drush upgrade_status:analyze
Analyze projects for deprecations and output results. Supports multiple output formats for different use cases including CI/CD integration.
drush upgrade_status:checkstyle
Deprecated. Analyze projects and output results in checkstyle XML format. Use 'drush upgrade_status:analyze --format=checkstyle' instead.
Troubleshooting 6
Ensure you installed the module using Composer: 'composer require drupal/upgrade_status'. The module requires PHPStan and phpstan-drupal which are only installed via Composer. If using a custom bin-dir or vendor-dir in composer.json, the module will automatically detect these locations.
Increase the PHPStan memory limit by using Drush with the --phpstan-memory-limit option: 'drush upgrade_status:analyze --phpstan-memory-limit=2G mymodule'. For web-based scanning, consider increasing PHP's memory_limit in php.ini.
The module uses HTTP requests to isolate PHP fatal errors during scanning. This may fail in some container or reverse proxy setups. Check that the site can make HTTP requests to itself. If using the built-in PHP server (php -S), HTTP sandboxing is automatically disabled as it doesn't support concurrent requests.
Run Drupal's update check first: navigate to Administration > Reports > Available updates > Check manually, or run 'drush pm:security' to refresh update information. Then return to Upgrade Status to see updated compatibility data.
Install Composer Deploy (drupal/composer_deploy) for Composer-managed sites or Git Deploy (drupal/git_deploy) for Git-deployed sites. These modules provide accurate project identification based on deployment metadata rather than directory structure heuristics.
The module automatically categorizes deprecations removed after the next major version as 'ignore'. For example, deprecations removed in Drupal 13 are ignored when upgrading to Drupal 11. Review the full deprecation message to understand the removal timeline and plan accordingly for future upgrades.
Security Notes 4
- The module requires the 'administer software updates' permission which is typically restricted to trusted administrators
- Scan results are stored in Drupal's key-value storage and persist between sessions
- The module makes HTTP requests to itself during batch processing to isolate PHP fatal errors - ensure your firewall allows localhost requests
- Exported HTML/ASCII reports may contain file paths that reveal server directory structure - treat exports as internal documentation