Org-Dependent Unlocked Package

An unlocked package built against metadata that stays outside the package, for brownfield orgs that can't fully modularize.

Definition

An org-dependent unlocked package is a 2GP unlocked package variant that's allowed to reference metadata living outside the package, custom fields, other objects, permission sets, without declaring every one of them as a formal dependency. A standard (org-independent) unlocked package has to be self-contained enough to install cleanly into an empty scratch org; an org-dependent one can't, since it assumes the target org already has certain metadata in place. That tradeoff makes it the practical entry point for teams with a large, tangled legacy org who can't cleanly separate metadata into independent packages yet, but still want 2GP's versioning and CI/CD benefits. The catch: org-dependent packages can't be installed into a fresh scratch org for isolated testing, which limits how much of the CI pipeline can validate a version before it ships. See our 2GP gotchas guide for where this trips teams up.

In practice

How it works in Serpent

Serpent builds and versions org-dependent unlocked packages the same way it handles any other 2GP package type, tracked by task, promoted with dependency awareness, without requiring a team to script sf package version create by hand. Because org-dependent packages can't validate cleanly in an empty scratch org, Serpent's preflight checks run against a representative sandbox instead, catching missing-dependency errors before a real deployment does. See 2GP CI/CD in Serpent for how both package types fit the same pipeline.

Common questions