Package
A Package in Salesforce is a container of metadata that can be distributed across orgs as a single deployable unit.
Definition
A Package in Salesforce is a container of metadata that can be distributed across orgs as a single deployable unit. Packages bundle objects, fields, Apex classes, Lightning components, page layouts, validation rules, flows, and any other deployable metadata into a versioned artifact that installs cleanly into another org. Packages are how AppExchange ISVs ship their products, how internal teams modularize their org configuration, and how Salesforce DX projects publish reusable components across an enterprise.
Salesforce supports four package types: Managed (publisher-owned, locked from customer edits, sold via AppExchange), Unmanaged (open-source-style, fully customer-editable after install), Unlocked (Salesforce DX modern format with source control and dependency declarations, the recommended type for internal team packages), and 2nd-Generation Managed (the modern managed package format for ISVs, replacing the legacy 1st-generation managed). The choice of package type determines distribution capabilities, customer-side editing rights, and the development workflow that produces the package.
How Salesforce Packages bundle metadata for distribution across orgs
The four package types and what each is for
Managed packages (1st Gen and 2nd Gen): publisher-owned with namespace prefixes, distributed via AppExchange, protected from customer modification. Customers can extend but not modify the package internals. Unmanaged packages: open metadata, customer-editable after install, useful for one-time deployments and code samples. Unlocked packages: modern DX format for internal teams, namespaced or not, customer-editable, designed for source-control workflows. 2nd-Generation Managed: the modern managed package format with DX project structure, faster releases, and better dependency management than 1st-Gen.
Namespace and the prefix system
Managed packages carry a Namespace Prefix registered with Salesforce at publication time. The prefix (acme, dsfs, conga) appears in front of every API name shipped by the package: acme__Custom_Object__c, conga__Document__c. Namespaces are unique across the entire Salesforce platform and cannot be renamed. The namespace protects the package from collisions with customer-org customizations; an acme__Custom_Object__c does not conflict with a customer''s Custom_Object__c. Unmanaged and most Unlocked packages skip the namespace; they install API names without prefixes and collide if customers already have matching names.
Package versioning and the upgrade story
Every package release is a versioned snapshot. Customers install a specific version (1.0, 1.1, 2.0) and upgrade to newer versions when the publisher releases them. Managed packages support push upgrades (publisher initiates) and pull upgrades (customer initiates). Unlocked packages support similar semantics via Salesforce CLI deployment commands. The versioning model is what makes packages safe to deploy in production; new releases install over old ones with predictable upgrade behaviour rather than free-form metadata changes.
Source-driven development with 2nd Gen and Unlocked
Modern packages (2nd-Gen Managed and Unlocked) are built from source-control-friendly metadata. The Salesforce DX project structure declares which metadata belongs to which package, dependencies between packages, and version metadata in package.json-style files. The Salesforce CLI builds and publishes packages from a Git repository. This source-driven workflow replaces the legacy 1st-Gen managed package experience of editing inside a packaging org, which was hard to reconcile with Git and CI/CD pipelines.
Package dependencies and the build order
Packages can depend on other packages. An extension package requires a base package; the platform enforces install order. Dependencies are declared in the DX project for 2nd-Gen and Unlocked, or registered in the Subscriber Support Console for 1st-Gen. Circular dependencies are not allowed. For first-party internal package strategies, declaring dependencies between packages is the way to enforce build order and prevent half-installed states.
The AppExchange path for managed packages
Managed packages are the path to listing on AppExchange. The publisher creates a Partner Org, builds the package, completes Security Review (a Salesforce-run audit of code quality, security, and AppExchange policy compliance), and lists the package on AppExchange. Security Review is non-trivial (3-6 months for a first-time submission) and is the largest friction point for ISVs entering the ecosystem. Unmanaged and Unlocked packages cannot list on AppExchange; that channel is managed-only.
Choosing the right package type for your use case
Decision tree. AppExchange ISV product: Managed (preferably 2nd-Gen). Internal team distributing reusable metadata across orgs: Unlocked. Code samples or one-time deployments where customer-editable is fine: Unmanaged. Legacy Vlocity-style apps and old AppExchange listings: 1st-Gen Managed (do not start new work here). The pricing model is also different: AppExchange listings charge customers per seat; internal Unlocked packages are free.
Creating and distributing a Salesforce package
The setup varies by package type. The modern path (Unlocked or 2nd-Gen Managed) uses Salesforce DX and the CLI; the legacy path (1st-Gen Managed or Unmanaged) uses a packaging org and the classic Package Manager UI.
- Pick the package type
Decision tree: AppExchange product = Managed (2nd-Gen preferred). Internal reusable component = Unlocked. One-time deployment = Unmanaged. Avoid 1st-Gen Managed for new work.
- Set up the Salesforce DX project (Unlocked or 2nd-Gen)
Install Salesforce CLI. Run sf project generate to create a DX project. Configure sfdx-project.json with the package name, namespace (if managed), and dependencies. Commit to Git.
- Develop in a scratch org
Create a scratch org (sf org create scratch). Build objects, fields, Apex, components in the scratch org or directly in source. Pull or push changes between scratch org and Git.
- Build the package version
Run sf package version create with the version number, definition file, and release notes. The CLI builds the version and registers it in Salesforce. Promote the version to released status before allowing customer installs.
- Install in target orgs
Customers install via the package URL (sf package install or the Setup, Install Package UI). Test installation in a sandbox first. For AppExchange-listed managed packages, customers install via the AppExchange listing page.
Managed (2nd Gen or 1st Gen), Unmanaged, or Unlocked. Each has different distribution channels, customer-editing rights, and development workflows.
Required for managed packages. Optional for unlocked. Unique across the Salesforce platform; cannot be renamed.
Major, minor, patch versioning. Major changes (1.0 -> 2.0) may require migration logic; minor and patch upgrades install cleanly.
AppExchange listing (managed only), direct install URL, Salesforce DX deployment. Pick based on audience and packaging type.
- Namespace prefixes are unique across the Salesforce platform and cannot be renamed. Pick carefully and check availability before publishing.
- AppExchange Security Review is a 3-6 month process for first-time submissions. Plan it as a project, not an afterthought.
- Managed packages cannot be uninstalled to roll back a bad upgrade. Test in sandbox before pushing customers an upgrade.
- Unmanaged packages collide with existing customer metadata on install if API names overlap. Use unique enough names.
- 1st-Gen Managed development happens in a packaging org, not source control. Avoid 1st-Gen for new work; the workflow is incompatible with modern CI/CD.
Trust & references
Cross-checked against the following references.
- Second-Generation Managed PackagingSalesforce Developer Docs
- Unlocked Packages OverviewSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Package.
- Packages OverviewSalesforce Help
- AppExchange Security ReviewSalesforce Help
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 Salesforce Package?
Q2. What are the two main package types?
Q3. What's the modern packaging approach?
Discussion
Loading discussion…