Andrew Hanna

Andrew Hanna

Unmanaged Package in Salesforce: What It Is and How to Move Off

Unmanaged Package in Salesforce: What It Is and How to Move Off

TL;DR: An unmanaged package in Salesforce is a first-generation bundle of metadata that you install once and then own completely: every component becomes editable in the target org, there is no namespace, no IP protection and no upgrade path. It is the right tool for templates, sample apps and one-time transfers. For anything you plan to maintain, move it to an unlocked package.

What is an unmanaged package in Salesforce?

An unmanaged package is a one-time distribution mechanism. You collect components such as custom objects, fields, Apex classes, flows, layouts and reports, upload them from a packaging org, and share an install link. On install, the contents are unpacked into the target org and behave as if an admin had built them there.

That is the whole trade-off. The installer gets full control, and the publisher gives up any way to push fixes later. For a side-by-side view of both models, see managed vs unmanaged packages in Salesforce.

When should you use an unmanaged package?

  • Templates and starter kits that the installer is expected to fork and customise.
  • Sample and open-source apps, where visible code is the point.
  • One-time transfers of a set of metadata between unrelated orgs.
  • Consulting accelerators, such as objects, reports and permission sets a client adapts to its own process.

If the words version, upgrade or subscriber appear anywhere in your plan, an unmanaged package is the wrong choice.

How do you create and install an unmanaged package?

  1. In the source org, open Setup and search Package Manager in Quick Find.
  2. Create a new package and give it a clear name. Leave it without a namespace.
  3. Add components from the Components tab. Salesforce adds many dependent components for you, so review the list before you upload.
  4. Click Upload. When the upload succeeds, Salesforce emails you an installation link.
  5. Open that link while logged in to the target org (sandboxes use the test login domain), choose who gets access, and install.
  6. Test in a sandbox first. Installed components can collide with existing metadata of the same name.

What are the limits of unmanaged packages?

  • No upgrades. You cannot install a new version over an old one. You uninstall and reinstall instead.
  • Uninstall deletes data. Removing the package removes its custom objects and fields, and the records in them.
  • No IP protection. All Apex, formulas and logic are visible and editable in the installing org.
  • No namespace. Components land in the default namespace, so name clashes with existing metadata are on you.
  • Org limits apply. Installed custom objects, fields and tabs count against the installing org's edition limits.
  • No change tracking. Once installed, nothing ties the components back to a version, so drift is invisible unless you track it in source control.

The uninstall-to-upgrade rule is where teams lose data. Before you remove an installed package, capture a known-good state. In Serpent, the Backups view does exactly that, recovers supported org metadata and records, and keeps a Restore History. It complements rollback, and already-deleted data is still harder to reverse cleanly, so back up first. Steps are in the backup and restore guide.

How do you migrate an unmanaged package to an unlocked package?

This is the part most guides leave out. There is no in-place conversion, so you rebuild the package from source:

  1. Inventory the components. List what the unmanaged package installed and what has been customised since.
  2. Retrieve to source. Write a package.xml for those components and run sf project retrieve start --manifest package.xml --target-org source. Our Salesforce CLI guide covers the setup.
  3. Commit to Git. From here, version control is the source of truth.
  4. Split by dependency. If the bundle mixes a shared data model with features, separate them into base and feature packages. The rules are in cross-package dependency resolution.
  5. Create the unlocked package. Run sf package create --package-type Unlocked --path force-app against your Dev Hub, then cut a version with sf package version create --code-coverage. Apex needs at least 75% coverage before you can promote it.
  6. Rehearse in a sandbox with realistic data before you touch production.

For step 6, Serpent seeds sample or masked data during environment setup and release pipelines, so scratch orgs and refreshed sandboxes come back populated without a manual script run. If you are building for AppExchange instead, the destination is a managed 2GP package; read the secrets of second-generation managed packages before you start.

Unmanaged vs unlocked vs managed: which fits?

  • Unmanaged: one-time copy, editable, no upgrades. Templates and samples.
  • Unlocked (2GP): source-driven, versioned, upgradeable, namespace optional. Internal apps.
  • Managed (2GP): namespaced, IP-protected, upgradeable. Commercial AppExchange apps.

Serpent's package development support builds, versions and ships 1GP, 2GP and managed packages on every plan, and maps dependencies so version conflicts surface before a target org sees them. More how-tos live in our SF Guides.

FAQ

Can you upgrade an unmanaged package?

No. You must uninstall the old version and install the new one, which deletes data in its custom objects and fields.

Do unmanaged packages have a namespace?

No. Components install into the default namespace, which is why name collisions are possible.

Can I list an unmanaged package on AppExchange?

No. Commercial AppExchange distribution uses managed packages, which carry a namespace and pass security review.

Can I convert an unmanaged package into an unlocked package?

Not in place. Retrieve the metadata to source control, then create a new unlocked package from it.

Related Articles

Curious about faster shipping before you dive in? Let's talk

Commitment free!