Patch Development Organization
A patch development organization is a special Developer Edition org that Salesforce generates from a specific major release of a Managed - Released package.
Definition
A patch development organization is a special Developer Edition org that Salesforce generates from a specific major release of a Managed - Released package. An ISV uses it to build patch versions, which are small bug fixes for an existing package version. Customers can install the patch without being forced onto a new major version.
The patch org is deliberately constrained. You can fix defects and adjust existing behavior, but you cannot add new components, delete components, or change access controls. That limit is what makes a patch safe to push to live subscriber orgs automatically.
How patch orgs fit the ISV release cycle
What a patch version actually is
A package version number follows the format majorNumber.minorNumber.patchNumber, for example 2.1.3. The first two numbers cover major and minor releases, where you add features and components. The third number is the patch level, and it exists for one reason: shipping fixes to a version that is already in the wild. When you upload a patch, the patch number increments by one. A package that shipped as 2.0 becomes 2.0.1 after the first patch. A subscriber sitting on 2.0 can move to 2.0.1 and keep every setting, because nothing structural changed. They are not pushed to 2.1 or 3.0, which might carry features they have not tested or licensed. This matters for support economics. Without patches, a single bad line of Apex in a released version would force every affected customer through a full upgrade cycle just to get the fix. Patches let an ISV repair the exact version a customer runs, on that version's own track, with far less disruption on both sides.
Why it is a separate Developer Edition org
You do not patch inside your main packaging org. Salesforce spins up a separate Developer Edition org that is seeded from the exact metadata of the major release you select. This gives you a clean, version-accurate workspace that matches what subscribers have installed, not your latest in-progress build. The separation is intentional. Your packaging org may already contain work for the next major release, with new objects, fields, and classes that do not belong in a patch. If you fixed bugs there, you would risk dragging unreleased changes into a patch that ships to production customers. The patch org isolates the fix from everything newer. Each patch development org is tied to one major release. If you maintain several supported releases at once, such as 2.x and 3.x, you create a distinct patch org for each. You log in to the relevant patch org, make the change against that exact baseline, run your tests, and upload the patch from there. The org's whole purpose is to keep the fix scoped to the version it targets.
The guardrails: what you cannot change
Development inside a patch org is restricted by design, and the rules are strict. You cannot add new package components, and you cannot delete existing ones. API and dynamic Apex access controls cannot change for the package. You cannot deprecate any Apex code. The Apex-specific limits go further. You cannot add new class relationships such as extends. You cannot add access modifiers such as virtual or global to existing members. You cannot add new web services, and you cannot add new feature dependencies. Each of these could change the package's external surface or break compatibility during an automatic upgrade. The logic behind every rule is the same. A patch is meant to install silently on a live org, often through a push upgrade the subscriber never initiates. So the change must not introduce anything that could cause a compile-time error against existing customer code, alter how integrations call the package, or expand what is exposed. If a fix needs a new field or a new global method, that is not a patch. It belongs in the next minor or major release instead.
Creating the patch org from Setup
In a first-generation managed package, you create the patch org through the packaging org's Setup. Under the package detail, you open the patch organizations area and start a new patch. The key control is the Patching Major Release dropdown, where you pick which released version you want to patch. Only versions with a release type of Managed - Released appear as options. Beta versions cannot be patched, because beta packages are not meant for production and are not upgradeable in the same way. Once you choose the major release and submit, Salesforce provisions the patch development org and emails the login credentials to the address on file. From there the flow is familiar. You log in to the new patch org, locate the defect, write the fix, and add or update tests to prove it. Because the org mirrors the released version, your fix is validated against the real baseline. When the tests pass, you upload the package from the patch org, which produces the next patch version, ready to distribute to subscribers.
Distributing the patch to subscribers
A finished patch version reaches customers in two ways. Subscribers can install it themselves like any other package version, moving from 2.0 to 2.0.1 when they choose. This is the pull model, and it suits fixes that are useful but not urgent. For critical fixes, an ISV usually pairs patches with push upgrades. A push upgrade lets the publisher install a newer version into subscriber orgs without each customer taking action. Because a patch is constrained to safe, compatible changes, it is well suited to being pushed: the upgrade should not break customizations, integrations, or existing code. This combination is how ISVs close out security or data-integrity bugs quickly across a large install base. The result is a real product lifecycle. An ISV ships a major release, learns about a defect in production, patches the exact version customers run, and rolls the fix out with minimal friction. This post-release maintenance path is one of the capabilities that separates managed packages from simpler, unmanaged distribution.
Patches in second-generation packaging
The concept carries into second-generation managed packages, but the mechanics shift toward source-driven tooling. You do not provision a clickable patch org from Setup the same way. Instead you work from a version-controlled project and the Salesforce CLI, and you create a patch version by building a new package version off the released one. The version scheme expands slightly in 2GP, using major.minor.patch.build, so the build component gives every create a unique identifier. The intent is identical to 1GP: a patch is a low-risk fix that lets customers on an older release stay put while still getting the repair, rather than being forced to a new major version. The trade-off between the generations is about workflow, not purpose. First-generation packaging leans on org-based patch development and the Setup UI. Second-generation packaging treats the package as code, so patches flow through the same scratch-org and CLI pipeline you use for everything else. Newer ISV projects generally build on 2GP, but the patch idea, fix small things without a forced upgrade, stays the same.
Create a patch development org and ship a fix (1GP)
Here is the first-generation flow for spinning up a patch development org and shipping a fix to a released managed package. You run this from your packaging org, not a sandbox.
- Open the package and start a patch
In the packaging org Setup, go to the managed package detail and open the patch organizations section. Choose to create a new patch development organization for the package.
- Pick the major release to patch
Use the Patching Major Release dropdown to select the released version you want to fix. Only versions with a release type of Managed - Released are eligible, so beta uploads will not appear.
- Log in and write the fix
Salesforce provisions the patch org and emails the credentials. Log in, reproduce the defect, make the correction to existing components only, and update the relevant Apex tests so the fix is covered.
- Upload the patch version
From the patch org, upload the package as Managed - Released. The patch number increments automatically (for example 2.0 becomes 2.0.1), producing a version you can distribute or push to subscribers.
The dropdown that picks which released major version the patch org is built from; it sets the baseline metadata you fix against.
Must be Managed - Released for a version to be patchable; beta packages cannot be patched.
Choose between letting subscribers install the patch themselves or sending it through a push upgrade for urgent fixes.
- You cannot add or delete components in a patch org. If a fix needs a new field, class, or global method, it must go in a minor or major release instead.
- Do not add Apex extends relationships, new global or virtual modifiers, new web services, or new feature dependencies; these break the patch's upgrade-safety rules.
- Each patch org is bound to one major release. Maintaining several supported releases means creating and tracking a separate patch org for each.
- Before push-upgrading a patch to live orgs, test it against representative subscriber data, since the install happens without the customer's involvement.
Prefer this walkthrough as its own page? How to Patch Development Organization in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Patch Development Organization.
Hands-on resources to go deeper on Patch Development Organization.
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. What is a Patch Development Organization created from in Salesforce managed packaging?
Q2. How does a Patch Development Organization differ from an ordinary Developer Edition org?
Q3. When does an ISV partner typically spin up a Patch Development Organization?
Discussion
Loading discussion…