How do I use the Adobe Commerce Upgrade Compatibility Tool?

The Magento Upgrade Compatibility Tool is Adobe’s command-line scanner for checking custom code against a newer Adobe Commerce release. To use it, download it from Adobe’s Composer repository with your Commerce access keys. Then point its upgrade:check command at your store’s code and target version. Access is limited to Adobe Commerce, so Magento Open Source stores can’t download it.

Which editions can run the Magento Upgrade Compatibility Tool?

Adobe states in its Upgrade Compatibility Tool prerequisites that the tool is available for Adobe Commerce instances only. Adobe also labels it “PaaS only”, which means it applies to cloud and on-premises projects.

Magento Open Source teams have to scope upgrades without the UCT. The free Magento Coding Standard runs through PHP_CodeSniffer and works on any Magento 2 codebase. A trial upgrade on staging then catches what static checks miss.

How to use the Magento Upgrade Compatibility Tool, step by step

Using the Upgrade Compatibility Tool takes six steps, from access keys to a re-run after fixes.

1. Set up Adobe Commerce access keys and a Linux server

Add your Adobe Commerce access keys to auth.json (default location ~/.composer), or the Composer download fails outright. You need a Linux machine with PCNTL and the other required PHP extensions, plus Node.js. Give the tool at least 2 GB of RAM. You can install it on a separate box, as long as it can read the store’s source code.

2. Download bin/uct with Composer

composer create-project magento/upgrade-compatibility-tool uct --repository https://repo.magento.com
chmod +x ./uct/bin/uct

PhpStorm users can point the Magento PhpStorm plugin at this install and run the checks inside the IDE.

3. Run the Adobe Commerce UCT upgrade:check scan

bin/uct upgrade:check /var/www/magento -c 2.4.9

bin/uct reads your current version from the installation. If you leave out -c, it targets the latest stable release. Enter the version without quotes, per Adobe’s upgrade:check run guide. The target can’t be older than 2.3 or older than the version you already run.

4. Filter UCT results and export a JSON or HTML report

bin/uct upgrade:check /var/www/magento -c 2.4.9 -i --min-issue-level error --json-output-path ./uct-report.json --html-output-path ./uct-report.html

The -i flag hides issues your current version already has, so only new ones from the upgrade remain. Each issue in the report comes with an error code, a severity level, and the affected module. That JSON output is easy to wire into CI. A GitHub Actions or GitLab CI step can parse it and fail the build on critical issues.

5. Check core edits, database schema, and GraphQL changes

• core:code:changes: compares your installation to a clean vanilla copy and lists any edits made directly to core code.
• dbschema:diff: lists database schema differences between two versions, for example bin/uct dbschema:diff 2.4.7 2.4.9.
• graphql:compare: compares two GraphQL endpoints and flags breaking or dangerous schema changes, which matters for headless or PWA frontends.

6. Auto-fix deprecated code with bin/uct refactor

Run bin/uct refactor <dir> to fix a small set of issues automatically. The set covers three cases only: deprecated argument-less function calls, $this in templates, and final on private methods. Everything else needs a developer. Re-run upgrade:check after each batch of fixes so the issue count tracks your progress.

When to run the Magento Upgrade Compatibility Tool in an upgrade

Run the Upgrade Compatibility Tool first, before anyone estimates the upgrade. The count of critical issues and errors tells you how much custom code needs work. Keep re-running bin/uct through development, then finish with a full staging test. If critical issues sit in third-party modules, check the vendor’s changelog for a compatible release before patching them yourself. Our Magento development team can help you separate vendor problems from your own code.