Unlocked packages let teams deploy modular, editable Salesforce metadata with upgrade paths. This guide explains how to enable Dev Hub, create package versions, install across orgs, and follow best practices for governance and CI/CD.
What are Unlocked Packages?
Unlocked packages are a Salesforce packaging option designed for internal applications and DevOps workflows. They allow metadata to be packaged into modular units that can be installed and upgraded across orgs while still permitting edits post-installation. This makes them a strong choice for teams that need flexibility alongside structured release management.
Key Benefits
- Flexibility — Components in unlocked packages can be modified after installation.
- Modularity — Group related metadata for easier reuse and targeted upgrades.
- Upgradability — Create new package versions and upgrade installations while retaining important local changes when managed properly.
- Collaboration — Multiple developers can work on separate package modules using source control.
Step-by-step: Create an Unlocked Package
Follow these practical steps to get an unlocked package from Dev Hub to another org.
1. Enable Dev Hub
Enable Dev Hub in the production or dedicated packaging org:
- Setup → Dev Hub → Enable Dev Hub
- Enable 2nd Generation Managed Packaging (2GP) if you plan to create managed or unlocked packages.
2. Install Salesforce CLI
Download and install the Salesforce CLI (sfdx) from the official site. The CLI is required to create packages, versions, and run CI/CD commands.
3. Authenticate with your Org
Open a terminal and run:
bash sfdx force:auth:web:login -d -a DevHub
This sets DevHub as the default Dev Hub alias—replace if needed.
4. Create the Unlocked Package
Run:
bash sfdx force:package:create --name MyPackage --description "My First Package" --packagetype Unlocked --path force-app --nonamespace --targetdevhubusername DevHub
Options explained:
- –name — Package name
- –packagetype Unlocked — Create an unlocked package
- –path — Directory containing source (typically force-app)
- –nonamespace — Skip namespace if you don’t need it
5. Create a Package Version
Create a version that can be installed in other orgs:
bash sfdx force:package:version:create -p MyPackage -d force-app -k mysecretkey --wait 10 -v DevHub --codecoverage
Notes:
- -k mysecretkey — Optional install key used during package installation.
- –wait 10 — Wait up to 10 minutes for build/validation.
- –codecoverage — Include Apex code coverage requirements if needed.
6. Install the Package in a Target Org
Use the install URL returned after version creation or run an install command. If using the URL, open:
https://<yourdomain>.my.salesforce.com/packaging/installPackage.apexp?p0=<YourPackageVersionId>
Provide the install key (if set), select installation visibility (All Users or Specific), and install.
Best Practices
- Use a single namespace only if necessary — namespaces complicate upgrades.
- Track and document any direct changes made in production after package installation.
- Test package versions in a full sandbox or staging org before production upgrades.
- Monitor and manage component dependencies carefully to avoid upgrade conflicts.
- Use source control (Git/SVN) to track changes and manage release branches.
- Automate builds, tests, and deployments via CI/CD (Jenkins, GitHub Actions, GitLab CI, etc.).
Quick FAQ
Q: How do unlocked packages differ from managed/unmanaged?
Unlocked packages combine the upgrade path of managed packages with the editability of unmanaged packages — they can be upgraded and still allow post-install edits (subject to governance).
Conclusion
Unlocked packages are a powerful tool for Salesforce teams that want modular, maintainable deployments with the flexibility to adapt after installation. When paired with source control and CI/CD pipelines, they enable predictable releases and collaborative development.
This approach matters for Salesforce admins, developers, and business users because it balances control and agility—reducing deployment friction while still allowing production-level adjustments when business needs change.