Patch
A patch is a package version that ships bug fixes to a specific major.minor release of a Salesforce managed package, without adding new features. It keeps the same major and minor numbers and incre…
Definition
A patch is a package version that ships bug fixes to a specific major.minor release of a Salesforce managed package, without adding new features. It keeps the same major and minor numbers and increments only the patch segment, so a subscriber on an older release can take the fix while staying on the functionality they already know.
In second-generation managed packaging (2GP), a patch lives in the four-part version number major.minor.patch.build. Partners build it from source with the Salesforce CLI, then customers install it as a small, low-risk upgrade. The point is to decouple urgent fixes from feature releases, so nobody has to swallow unwanted changes just to clear a defect.
How patches fit Salesforce package versioning
Where the patch number sits in the version
Every 2GP package version carries a four-part number: major.minor.patch.build. The major segment signals large or breaking change. The minor segment marks new, backward-compatible features. The patch segment is reserved for fixes against an already-released major.minor line. The build segment is an internal counter that increments each time you generate a version, and you can set it to the literal NEXT so the CLI assigns the next available value automatically. A patch keeps major and minor frozen and bumps only the patch number. If your released version is 2.5.0.1 and you find a defect, the fix ships as 2.5.1, not 2.6 or 3.0. That single rule is what makes a patch safe to install. Subscribers know the feature surface has not moved, so the upgrade is about correcting behavior, not learning anything new. You record this number in the versionNumber field of your package directory inside sfdx-project.json before you create the version.
Why ISVs lean on patches
Picture an AppExchange vendor with customers spread across several releases of the same product. One enterprise account is parked on 2.5 because a downstream integration depends on it. A defect surfaces that affects exactly that account. Without a patch, the vendor has two bad options. Force the customer onto the latest feature version and risk breaking the integration, or leave the bug unfixed until the customer is ready to upgrade. A patch removes that false choice. The vendor produces 2.5.1, the customer installs only the fix, and the integration keeps working. Meanwhile other customers move to new feature versions on their own schedule. This is standard practice for mature ISV support and a big reason partners care about clean version discipline. It also keeps support conversations honest. You can tell a customer the patch changes one thing, point them at release notes for that patch line, and avoid the dread that comes with a full version jump.
Rules a patch has to follow
A patch is not a free pass to ship anything. Salesforce constrains it to minor, fix-shaped changes so the install stays low risk. The patch must target an existing released major.minor version and respect package ancestry, the chain that links a new version back to the ones before it. You are correcting behavior in components that already exist, not redesigning the package. Adding sweeping new functionality belongs in a minor or major version instead. If a change does not fit inside the patch boundaries, the CLI will not let you create it as a patch, which is the system protecting subscribers from surprise. Treat the patch as a scalpel. It is meant for a defect with a known fix, not for slipping a feature past your own release process. When the change is genuinely small and corrective, you create the patch package version directly from the CLI and it is ready to install once it passes validation.
Patches in 2GP versus first-generation packaging
Patches existed long before 2GP, but the mechanics were heavier. In first-generation managed packaging (1GP), you created and uploaded patches from a dedicated patch development organization tied to the major.minor version you were fixing. That org was a separate environment you had to request and manage, and it constrained what you could touch. Second-generation packaging modernized this. There are no patch orgs in 2GP. Your version control system is the source of truth, and you build the patch from source with the Salesforce CLI like any other package version. That shift matters for teams that want repeatable, scriptable releases. A continuous integration pipeline can compute the next patch number, create the version, run tests, and promote it without a human clicking through a packaging org. If you are still on 1GP, patches are one more reason teams evaluate the move to managed 2GP, where the whole packaging lifecycle runs through the CLI.
How subscribers receive a patch
From the customer side, a patch installs the same way any package upgrade does, just with a smaller footprint. They take version 2.5.1 in place of 2.5.0 and the fix lands. Because the major.minor line is unchanged, the upgrade does not introduce new features they have to evaluate or retrain on. For many admins that is the difference between approving an install this week and deferring it for a quarter. Partners can also push a patch to subscribers rather than waiting for each org to pull it. Push upgrades let an ISV deliver a package version to installed orgs, which is well suited to a critical fix that should not sit unapplied. Whether pulled or pushed, the patch carries the same promise: this version corrects something, it does not change what the product does. That predictability is the entire value of treating fixes and features as separate version tracks.
Where patches show up beyond packaging
The word patch also appears in everyday Salesforce conversation outside of ISV packaging, and it helps to keep the senses straight. Salesforce ships three major platform releases a year (Spring, Summer, and Winter), and between them it pushes patch releases to its own service to fix issues. Those are operated by Salesforce on its instances, not something a customer versions or installs. In a development team, people often say patch loosely to mean any small, targeted fix to existing code or configuration, the opposite of a large feature change. That casual usage lines up with the formal packaging meaning: small, corrective, low risk. When you are writing release notes, a change set description, or a deployment plan, calling a change a patch sets an expectation. Reviewers read it as a fix with limited blast radius, so reserve the word for changes that actually meet that bar and label real features as features.
How to create a 2GP patch version
Creating a 2GP patch means producing a package version that bumps only the patch segment of an already-released major.minor line, then promoting it for customers. There is no patch org. You work from source and the Salesforce CLI.
- Confirm the released base version
Identify the released major.minor version you need to fix, for example 2.5. The patch must target an existing released line and respect package ancestry, so verify the base version exists and is promoted before you start.
- Set the patch version number
In sfdx-project.json, set versionNumber for the package directory to the next patch, such as 2.5.1.NEXT. Keep major and minor identical to the base. NEXT lets the CLI assign the build number automatically.
- Make only fix-shaped changes
Commit the bug fix to your source. Keep the change minor and corrective. Adding broad new functionality belongs in a minor or major version, and the CLI will reject a patch that steps outside those bounds.
- Create the patch package version
Run the Salesforce CLI package version create command against your Dev Hub. It reads the version number from sfdx-project.json, builds the version from source, and runs validation including Apex tests.
- Promote and deliver
Promote the version from beta to released, then give subscribers the install link or push the upgrade to installed orgs. Customers on the base version take the patch as a small upgrade.
The major.minor.patch.build value in sfdx-project.json. For a patch, only the patch segment increases; build can be NEXT.
The org that owns your packages and creates versions. The CLI targets it to build and store the patch version.
The chain linking a new version to prior ones. A patch must respect ancestry so upgrades stay valid for installed subscribers.
Moving a version from beta to released. Only a released patch can be installed by customers in production orgs.
- A patch cannot change the major or minor number. If your fix needs those to move, it is no longer a patch.
- The CLI blocks patches that add sweeping new functionality. Reserve those changes for a minor or major version.
- Patches respect package ancestry. Skipping or breaking the ancestry chain can leave subscribers unable to upgrade cleanly.
- In first-generation packaging, patches still require a separate patch development org. Only 2GP removes that requirement.
Prefer this walkthrough as its own page? How to Patch in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Patch.
Hands-on resources to go deeper on Patch.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. In second-generation managed packaging, what does a Patch version of a package deliver?
Q2. How does the version number change when an ISV ships a Patch on top of package version 2.5?
Q3. Which change is NOT allowed in a Patch and must instead wait for a new minor or major version?
Discussion
Loading discussion…