Package Version
A Package Version in Salesforce is a specific numbered release of a managed or unlocked package that can be installed in subscriber orgs.
Definition
A Package Version in Salesforce is a specific numbered release of a managed or unlocked package that can be installed in subscriber orgs. Each version is immutable once released, has a unique 04t Id, and represents a snapshot of the package contents at that point in time. New versions add features, fix bugs, or change behavior; the package's version number (major.minor.patch.build) communicates the nature of changes to subscribers and to dependency-aware tooling.
Package versions are the unit of distribution for everything that travels through Salesforce's package mechanism, from AppExchange-distributed ISV apps to enterprise-distributed unlocked packages used across business unit orgs. Understanding how package versions work, how they relate to each other, and how to manage the upgrade path is essential for any team building or consuming packages on the platform. The version model has changed substantially between first-generation packaging and second-generation packaging (2GP), with 2GP introducing source-driven version creation, explicit dependency declarations, and finer control over upgrade behavior.
How Package Versions work
Version numbering and semantic meaning
Package versions follow a four-part numbering scheme: major.minor.patch.build (1.2.3.4). The convention follows semantic-versioning principles: a major version bump signals incompatible API changes, a minor version bump adds backward-compatible functionality, a patch version bump fixes bugs without changing behavior. The build number increments with each saved package version, providing a monotonic counter. ISVs use the major.minor.patch portion to communicate intent to subscribers, while the build number primarily serves as an internal identifier. The numbering discipline matters because subscribers make upgrade decisions partly based on the version number they see; a 2.0.0 release sends a different signal than 1.5.3.
Immutability and the released state
Once a package version is promoted from beta to released, it becomes immutable. Salesforce will not let you modify the contents of a released version. If a bug is found in version 1.2.0 that needs fixing, the path is to release version 1.2.1 with the fix rather than to patch 1.2.0. This immutability is essential for trust: subscribers who installed 1.2.0 know exactly what they got, and the same version produces the same install experience for every customer. Beta versions, by contrast, can be rebuilt with the same number, which is useful during development but unsuitable for production distribution.
Ancestor relationships and upgrade compatibility
Managed package versions declare an ancestor: the previous version they upgrade from. The ancestor chain determines what upgrade paths are valid. A version that does not declare any version as an ancestor is treated as a brand-new install rather than an upgrade. The platform uses the ancestor declaration to validate that breaking changes (removing components, changing field types) only happen at boundaries where subscribers expect breakage. Salesforce DX automates much of the ancestor tracking, but ISVs still need to understand the model to handle edge cases (forking a package, merging back, intentional breaking changes).
Beta versus released versions
Beta versions are mutable and intended for testing. An ISV can build multiple beta versions of 1.0.0 during development, with each one replacing the prior one. Beta versions can be installed in scratch orgs and sandbox environments but not in production. Released versions are immutable and installable anywhere. The promotion from beta to released is a one-way decision: after promotion, the version cannot be unpromoted, only superseded by a newer version. ISVs use beta versions for internal testing and pilot customer testing before committing to a released version for general distribution.
Dependency declarations
Second-generation packages support explicit dependencies between packages. Version 1.0.0 of an Accounting Integration package may depend on version 2.5.0 or higher of a Base Financials package. The dependency is declared in the sfdx-project.json file when building the version, and the platform validates dependencies during install: the dependent package's required version must be present in the subscriber org or the install fails. Dependency management lets ISVs split their offerings into multiple coordinated packages rather than building monolithic megapackages. The trade-off is more complex version-coordination logic across packages, which adds operational overhead.
Install URLs and version-specific deployment
Each released package version has a unique install URL. Subscribers click the URL or invoke the equivalent CLI command (sf package install) to install that specific version. The install URL becomes part of the ISV's distribution surface: published on AppExchange, shared with customers, used in documentation. Subscribers can install a specific older version if needed (subject to compatibility), but most installs target the latest version. ISVs that want to manage which version subscribers see typically remove older install URLs from their public distribution channels, leaving the latest as the canonical version while the older ones remain available for support cases that need them.
Version retirement and unsupported versions
ISVs retire older versions when they no longer want to support them. Retirement does not remove the version from existing subscriber orgs (subscribers continue to use whatever version they installed), but it removes the version from the public distribution and signals to subscribers that they should upgrade. Salesforce supports retired versions in the sense that they continue to function on the platform, but the ISV may not provide support tickets or new patches against them. Communicating retirement timelines clearly to subscribers is essential to maintaining good relationships; surprise retirement of a heavily used version generates significant subscriber friction.
First-generation versus second-generation versions
The version model differs significantly between first-generation managed packages (1GP) and second-generation packages (2GP). 1GP versions are tied to a specific packaging org and built through a less automated workflow; the version contents are essentially a snapshot of the org's metadata at package creation time. 2GP versions are source-driven and built from a Salesforce DX project, with explicit dependency declarations and modern CLI tooling. Most ISVs are migrating from 1GP to 2GP because the source-driven model integrates better with CI/CD and version control, but many existing packages remain on 1GP and continue to be supported. The version-management practices are similar across both models, but the tooling and the developer experience differ substantially.
Version planning and release cadence
ISVs and enterprise package teams develop a release cadence that balances feature velocity with subscriber stability. Common cadences include monthly minor versions for feature additions, quarterly major versions for significant capability releases, and emergency patch versions for critical bug fixes. The cadence affects subscriber experience: too frequent and subscribers cannot keep up with upgrades, too infrequent and the package falls behind market needs. Mature programs publish a public roadmap that signals what is coming when, giving subscribers visibility to plan their adoption. Beta versions support the release cadence: each major version starts as a beta available to pilot customers, gets feedback, and promotes to released after pilot validation. This pattern lets the ISV move quickly on the development side while protecting subscribers from premature releases.
Common version-management pitfalls
Three pitfalls recur in package version management. Skipping the ancestor declaration produces versions that subscribers cannot upgrade to from prior versions, forcing uninstall and reinstall. Promoting beta versions too early surfaces bugs in subscriber orgs that the publisher then has to fix through emergency patches, eroding subscriber trust. Forgetting to update the version number on the next build produces confusion about what is in which version. Each pitfall is preventable with disciplined release processes, but they all happen across ISVs that have not yet matured their release engineering. The Partner Community shares horror stories and best practices freely, which helps newer ISVs learn from others rather than discovering each pitfall the hard way.
Create and manage Package Versions
Working with Package Versions spans the developer-side creation workflow, the testing and promotion workflow, and the ongoing version-lifecycle management. The walkthrough below covers the standard sequence for releasing a new package version from a Salesforce DX project.
- Set the target version in sfdx-project.json
Update the project's sfdx-project.json file to set the new version number. The versionNumber field follows the major.minor.patch.NEXT pattern, where NEXT auto-increments the build number during package version creation. Increment the major, minor, or patch number based on the nature of the changes per semantic versioning. Document the version's changes in a changelog before building.
- Build the new package version
Run sf package version create with the appropriate flags: the package alias, version number override if needed, the ancestor version, any test running options. The command validates the source, runs the configured tests, and produces a beta version with a 04t Id. The build can take minutes to hours depending on the package size and test complexity. Capture the 04t Id; this is the package version's unique identifier.
- Test the beta version in scratch orgs and sandboxes
Install the beta version in scratch orgs that simulate customer environments. Run the standard test scenarios: install on a clean org, install on an org with the previous version (upgrade test), exercise all major features, verify that any breaking changes are documented and acceptable. Engage pilot customers if appropriate. Iterate on the version with additional beta builds if bugs surface. The testing burden is what gates the promotion to released; do not rush this step.
- Promote to released and distribute
Once the beta version passes all testing, run sf package version promote to mark it as released. The version becomes immutable. Update the AppExchange listing or internal distribution channels with the new install URL. Communicate the release to subscribers through the standard channels. Schedule the retirement of older versions on a defined cadence. The new version is now the canonical install for new customers, with existing customers choosing when to upgrade.
- Released versions are immutable. Changes require a new version, not edits to the existing one.
- Ancestor declarations affect upgrade compatibility. Misconfigured ancestors break the upgrade path for subscribers.
- Beta versions cannot be installed in production. Only released versions are eligible for general distribution.
- Dependencies must be declared explicitly. Forgetting a dependency causes install failures in subscriber orgs.
- Version retirement does not affect existing installs. Subscribers continue to use retired versions until they explicitly upgrade.
Trust & references
Cross-checked against the following references.
- Second-Generation Managed PackagingSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Package Version.
- Packaging GuideSalesforce Developer Docs
Hands-on resources to go deeper on Package Version.
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 Package Version?
Q2. What's a common versioning scheme?
Q3. Why does backward compatibility matter?
Discussion
Loading discussion…