The Magento Quality Patches Tool (QPT) is Adobe’s Composer package, magento/quality-patches, for applying individual bug fixes to Adobe Commerce and Magento Open Source without a full upgrade. You run vendor/bin/magento-patches status to see available patches, apply or revert them by ID, and on Adobe Commerce Cloud list them under QUALITY_PATCHES instead.
QPT is easy to start using and easy to misuse. The commands are simple. The hard parts are deciding which patches belong in your codebase, making sure they survive a deploy, and keeping the list honest across upgrades. This guide covers the commands first, then the operating model that keeps a patched store maintainable.
What QPT is, and what it is not
Adobe describes QPT as a self-service tool for applying, reverting, and viewing information about quality patches. A few boundaries matter before you touch it:
- Quality patches, not security patches. Adobe is explicit that QPT is for quality fixes only. Security fixes ship in Adobe’s security releases and patches, which follow their own cadence.
- Case by case, not a substitute for upgrading. Adobe’s documentation says the tool should be used to pull in needed fixes on a case-by-case basis, and that upgrading to the latest version is still the best method.
- Not a place to stockpile fixes. Adobe also warns that applying large numbers of patches increases code complexity and makes upgrades harder.
- Not all patches are Adobe-verified. Atwix’s overview of the tool notes that patches created by the Magento community are not verified by Adobe’s QA team, which is worth knowing before you put one into production.
Both Adobe Commerce (on-premises and Cloud) and Magento Open Source can use it.
Installing the tool
On-premises and Open Source projects add the package with Composer. Adobe’s usage guide says Git or the patch utility must be installed first, because QPT applies patches with one of them.
composer require magento/quality-patches
On Adobe Commerce Cloud you do not install it separately. The magento/quality-patches repository on GitHub notes that it is a dependency of ece-tools from version 2002.1.2, and it updates when ece-tools updates.
New patches are released as new versions of the package, so the list you see is only as current as your installed version. Refresh it with:
composer update magento/quality-patches
Reading the status output
The command you will run most is:
./vendor/bin/magento-patches status
It prints a table of every patch available for your installed Magento version. New patches appear at the bottom. The columns that matter:
| Column | Possible values | What it tells you |
|---|---|---|
| Status | Applied, Not applied, N/A | Whether the patch is in your code. N/A means the status cannot be determined because of conflicts. |
| Type | Optional, Deprecated (plus Required and Custom on Cloud) | Optional is the normal QPT case. Deprecated means Adobe has retired the patch and recommends reverting it. |
| Details | Affected components, required patches, recommended replacement | Which modules the patch touches, what it depends on, and what replaces a deprecated patch. |
Two values deserve attention every time you read the table.
N/A usually means the files the patch targets have been changed by something else, such as another patch, a composer patch from a different source, or a version mismatch. Treat it as a question to answer, not something to ignore.
Deprecated on a patch you have applied means it is time to revert it and, if the Details column names a replacement, apply that instead.
Finding the right patch
There are two common entry points.
- Adobe Support points you to a patch ID. This is the case the tool was built for. You get an ID from a support ticket and apply it.
- You hit a core bug and search for a fix. Adobe publishes a searchable list of QPT patches, filterable by component, with descriptions of the issue each patch solves, grouped by QPT release. Search there by symptom or module before writing your own fix.
Before applying anything, read the patch description against your actual symptom and confirm it targets your exact Magento version. The status table only lists patches that apply to your installed version, which is a useful cross-check.
Applying and reverting patches
Apply one or more patches by ID:
./vendor/bin/magento-patches apply MAGETWO-XXXX
./vendor/bin/magento-patches apply MAGETWO-XXXX MAGETWO-YYYY
./bin/magento cache:clean
Revert specific patches, or everything QPT has applied:
./vendor/bin/magento-patches revert MAGETWO-XXXX
./vendor/bin/magento-patches revert --all
./bin/magento cache:clean
According to Atwix, QPT tracks what it has applied and refuses to apply the same patch twice or revert a patch that is not applied. Every operation is logged to var/log/patch.log, which is the first place to look when an apply fails or a teammate asks what changed.
Adobe’s own sequence for a safe apply is short: back up first, apply in a development or staging environment, clear the cache, test the specific behaviour the patch fixes, and only then promote it.
The part most teams get wrong: keeping patches after composer install
QPT applies a patch to the code in your project. On a typical on-premises deployment, the vendor directory is not committed. It is rebuilt with composer install on every build, which means a patch you applied locally does not travel with your code unless you make it.
Adobe’s usage guide does not prescribe a deployment workflow, so you need to pick one. The common options:
| Approach | How it works | Strengths | Weaknesses |
|---|---|---|---|
| Composer script | A post-install-cmd script runs magento-patches apply with a committed list of IDs |
Simple, keeps QPT as the source of truth | Every build depends on the patch applying cleanly |
| Build pipeline step | Your CI or deploy script runs the apply command after composer install |
Visible in the pipeline, easy to fail the build on error | Must be kept in sync with the patch list |
| Composer patches | The fix is managed as a patch file through a Composer patch plugin | All patches (QPT and your own) in one system | You lose QPT’s status and deprecation tracking for that fix |
Cloud QUALITY_PATCHES |
IDs listed in .magento.env.yaml, applied by ece-tools during build |
Native, declarative, applied on every deploy | Cloud only |
Atwix recommends the composer script route for non-Cloud projects: a post-install-cmd entry that runs a small script holding the list of applied patch IDs. Whichever option you choose, the principle is the same. The list of patches is code. It lives in version control, it is reviewed in pull requests, and the build fails loudly if a patch does not apply.
If your project already manages third-party fixes through Composer, our guide to Composer patches, lock files, and safe Magento upgrades covers how to keep patch sources consistent so QPT and other patches do not collide.
QPT on Adobe Commerce Cloud
Cloud makes this part simpler. Adobe’s Cloud guide to applying patches describes a declarative setup in .magento.env.yaml:
stage:
build:
QUALITY_PATCHES:
- MCTEST-1002
- MCTEST-1003
Commit and push the file, and ece-tools applies the listed patches during the build. To remove one, delete it from the list and push again.
The same guide documents the build order:
- Required patches from Adobe’s Cloud Patches for Commerce package.
- The optional QPT patches you listed in
QUALITY_PATCHES. - Your own custom patches from the
m2-hotfixesdirectory, applied alphabetically by file name. Files must end in.patch.
Adobe states that required Cloud patches cannot be skipped. Locally, php ./vendor/bin/ece-patches status, apply, and revert give you the same view, with apply running required, then optional, then custom, and revert running in the reverse order. Adobe recommends testing every patch in an Integration or Staging environment before Production.
The alphabetical rule for m2-hotfixes is worth remembering. If one of your custom patches depends on another, name the files so they sort in the right order, for example with a numeric prefix.
Upgrade hygiene: re-check every patch
Adobe’s guidance is direct: after upgrading, you must re-apply patches that are not included in the new version. In practice, an upgrade is the moment to audit the whole list.
A workable routine:
- Before the upgrade, export the current list of applied patch IDs from your composer script, pipeline, or
.magento.env.yaml. - After bumping Magento, run
composer update magento/quality-patchesso the tool knows about the new version. - Run status. Patches fixed in the new release typically drop off or stop applying cleanly. Remove those IDs from your list.
- Re-apply the rest one at a time, as Adobe suggests, so a failure points at a single patch.
- Revert anything now marked Deprecated and apply its recommended replacement if one is listed.
- Run your test suite. Patched behaviour is exactly the kind of thing regression tests should cover, which is why we recommend pairing QPT with automated PHPUnit and MFTF tests in CI.
Done this way, the patch list shrinks with every upgrade instead of growing forever. A store carrying dozens of quality patches is usually a sign that upgrades have been deferred for too long, a pattern we cover in our Magento 2.4.8 upgrade guide.
A patch register worth keeping
The status table tells you what is applied. It does not tell you why. Keep a short register next to the patch list in your repository with one line per patch:
- Patch ID
- The symptom or support ticket that justified it
- Date applied and who approved it
- The Magento version it was applied on
- The test or manual check that proves it works
When the next upgrade comes, this register turns a guessing exercise into a five-minute review. It also helps new developers and new agencies understand why the code differs from stock Magento, which is part of what a real Magento maintenance plan should include.
When to use QPT, a custom patch, or an upgrade
| Situation | Best option | Why |
|---|---|---|
| Adobe Support gives you a patch ID | QPT | Adobe-built, tracked, and revertible |
| A core bug matches a published QPT patch | QPT | Same as above, with no custom code to maintain |
| The bug is in your own or a third-party module | Fix the module or patch it via Composer | QPT only covers Magento core |
| No published fix exists and you need one now | Custom patch, documented in your register | Temporary until an official fix ships |
| Many patches pile up for the same version | Plan the upgrade | Adobe recommends upgrading over accumulating patches |
| A security issue | Apply Adobe’s security release or patch | QPT does not carry security fixes |
Getting help with Magento patching
Patching is routine work, but it touches every deploy and every upgrade, so the discipline around it matters. Our Magento development services cover upgrades, support, and patch management for Magento Open Source and Adobe Commerce, and our Hyva development services keep Hyva themes and compatibility modules in step with the core version underneath. Teams running more than one platform can also talk to us about Shopify development, Shopware development, and BigCommerce development. Learn more about Bemeir, see our technology partners, or reach out from the Bemeir homepage.
FAQ
What is the Magento Quality Patches Tool?
It is a Composer package, magento/quality-patches, that lets you view, apply, and revert individual quality patches for Adobe Commerce and Magento Open Source. On-premises projects use vendor/bin/magento-patches, and Adobe Commerce Cloud uses ece-patches plus the QUALITY_PATCHES setting in .magento.env.yaml.
Does the Quality Patches Tool include security patches?
No. Adobe states that QPT is for quality patches only. Security fixes are delivered through Adobe’s security releases and security patches, which should be applied on their own schedule regardless of what QPT patches you carry.
Why did my applied patch disappear after deployment?
On most on-premises setups the vendor directory is rebuilt by composer install during each build, so a patch applied by hand is lost. Commit the list of patch IDs and apply them automatically after composer install, through a Composer script or a pipeline step, so every build gets the same patches.
What does N/A mean in magento-patches status?
N/A means the tool cannot determine whether the patch is applied because of conflicts. That usually points to another patch or modification touching the same files, or a version mismatch. Check var/log/patch.log and the files the patch targets before deciding what to do.
Do I need to re-apply patches after a Magento upgrade?
Yes, for any patch the new version does not already include. Adobe recommends updating the magento/quality-patches package, checking status, re-applying the remaining patches one at a time, and clearing the cache. Patches fixed in the new release should be removed from your list.
