Magento 2: How to Apply Patch?

A patch is a diff against core or vendor code. Adobe ships them for security fixes, regressions, and one-off bugs that did not make it into a full release yet. If you are behind on patches, you are not just missing fixes. You are often running code Adobe already flagged as risky.

The method you use depends on where the store runs and who wrote the patch. Cloud has a pipeline for this. On-prem and Open Source do not. Same word, different workflow.

On-prem and Open Source

Adobe's apply patches guide (opens in new tab) lists three paths. For official Adobe patches, start with the Quality Patches Tool (QPT) (opens in new tab). That is what Adobe supports. Not git apply on a random file from a support ticket.

Install the package if it is not already there:

composer require magento/quality-patches

Find the patch ID in the QPT release notes (opens in new tab) for your exact Commerce version, then apply it:

vendor/bin/magento-patches apply ACSD-47920

Swap ACSD-47920 for whatever ID you need. Run on a branch. Run your smoke tests. Deploy like any other code change.

Standalone .patch files

You will still see raw .patch files in the wild. Support sends them. Agencies keep them in a shared drive from 2019. For those, drop the file in your project root and run one of these from there:

git apply your-patch-file.patch

patch -p1 < your-patch-file.patch

I reach for git apply first because the output is easier to read when something fails. patch -p1 is the older Unix approach and still works fine on most Linux hosts.

Test on staging before you touch production. If the patch does not apply cleanly, your installed version probably does not match what the patch was built for. That happens more than people admit.

Composer patches (custom only)

You can wire patches through cweagans/composer-patches in composer.json. Adobe is explicit about this: do not use that route for official Adobe-provided patches. It is for project-specific fixes you own. See the Composer section (opens in new tab) in the docs if you need the extra.patches setup.

Adobe Commerce on Cloud

Cloud handles most patching during deploy. The magento/magento-cloud-patches (opens in new tab) and magento/quality-patches (opens in new tab) packages work together through ece-tools. When you push, patches apply in this order:

1. Required cloud patches from the Cloud Patches package
2. Optional quality patches you listed in .magento.env.yaml
3. Custom .patch files in m2-hotfixes/, applied alphabetically by filename

You cannot skip the required ones. That is by design.

Optional quality patches

Add patch IDs under QUALITY_PATCHES in .magento.env.yaml (opens in new tab):

stage:
  build:
    QUALITY_PATCHES:
      - ACSD-47920
      - ACSD-48857

Commit, push, let the pipeline run. Check the deploy log if something looks off.

Custom patches in m2-hotfixes

For fixes Adobe has not packaged yet, put your .patch file in m2-hotfixes/ at the project root:

mkdir -p m2-hotfixes
cp my-fix.patch m2-hotfixes/
git add m2-hotfixes/my-fix.patch
git commit -m "Add custom hotfix for checkout issue"
git push

The deploy applies it automatically. No manual patch command on the server.

Local cloud environments

Before you push, you can dry-run everything locally. You need ece-tools 2002.1.2 or newer.

Check what is applied and what is pending:

php ./vendor/bin/ece-patches status

Apply the full stack (required, optional, and m2-hotfixes):

php ./vendor/bin/ece-patches apply

Patch operations log to var/log/patch.log. That file has saved me more than once when a deploy said "applied" but the bug was still there.

For a longer walkthrough with revert steps and branch workflow, see How to Apply Patches in Adobe Commerce (Magento 2 Cloud).

Finding the right patch

The Quality Patches Tool catalog (opens in new tab) is the source of truth for Adobe-issued patches on both cloud and on-prem. Filter by your Commerce version, read the affected components, check whether the patch is still relevant after your last upgrade.

If you are on cloud and have access to Site-Wide Analysis Tool (SWAT) (opens in new tab), the Patches tab cross-references QPT against your installed version. Worth a look before you start dropping files into m2-hotfixes.

Quick reference

Test on Integration or Staging first. Re-check custom patches after every Commerce upgrade. A hotfix that applied cleanly on 2.4.6-p3 can fail silently on 2.4.7.

You may also like,

How to Apply Patches in Adobe Commerce (Magento 2 Cloud)

Magento 2: How to Check Cron Job is Working?

Magento 2: How to Get Base URL?