Salesforce shipped the Package Migrations CLI to make 1GP-to-2GP migration easier (Salesforce 2GP Guide). Easier still doesn't mean painless. The metadata moves cleanly. The packaging org binding doesn't. And every ISV I've talked to who tried it underestimated the namespace step.

Pro Tip

TL;DR: Migrating a 1GP managed package to 2GP uses Salesforce's Package Migrations CLI, which converts metadata and package version history. The namespace stays the same, but the packaging-org dependency is removed. Plan for source extraction, Dev Hub setup, namespace linking, and a fresh 2GP package version. Existing customers don't need to reinstall.

Salesforce recommends 2GP for all new managed packages (Salesforce 2GP Guide). 1GP still works for existing packages, but new feature investment is going into 2GP. The practical reasons to migrate.

1/ Source-driven development. 2GP lives in your source control, not in a packaging org. Version control, code review, CI all work properly. 2/ Multiple packages per namespace. 1GP locks one namespace to one package. 2GP lets you ship multiple packages under the same namespace, which matters for modular products. 3/ Better CI/CD. Salesforce CLI commands integrate cleanly with GitHub Actions, GitLab, and similar. 4/ Agentforce metadata. 2GP covers most GenAI metadata types used for Agentforce; 1GP support is partial.

If you're shipping new features in 2026, 2GP is the path. The question is when to migrate, not whether.

The CLI handles three things automatically.

→ Metadata extraction. Pulls your 1GP package metadata from the packaging org into source. → Namespace preservation. Your existing namespace (1 to 15 character prefix) carries over. Customer-installed components keep their API names. → Package version history. 2GP picks up the version sequence from where 1GP left off.

What the CLI doesn't handle.

→ Dev Hub setup. You enable it manually. → Namespace registration into your Dev Hub's Namespace Registry. Separate step. → Source organization decisions. Folder structure, modularization, sfdx-project.json setup. → Anything outside the package itself. Test data, sandbox configurations, CI workflows.

Plan for 1 to 2 weeks of dedicated engineering time for a medium-complexity package. Less for simple. More if you have nontrivial dependency graphs.

1/ Enable Dev Hub in your production or business org. Required for 2GP package creation. 2/ Link your namespace to the Dev Hub's Namespace Registry by authenticating the org that owns the namespace. 3/ Extract package metadata using the Package Migrations CLI commands. Output lands in your local Salesforce DX project structure. 4/ Audit and reorganize source. Decide on modular package boundaries if you want to split (one of 2GP's main wins). Update sfdx-project.json with package directories. 5/ Create the 2GP package using sf package create --package-type Managed. Reference your namespace. 6/ Create the first 2GP package version with sf package version create. The CLI continues your 1GP version numbering. 7/ Promote the version to released with sf package version promote. 8/ Test the upgrade path in a scratch org or sandbox. Install your last 1GP version, then upgrade to the new 2GP version. Confirm data, customizations, and dependencies survive. 9/ Distribute the upgrade to customers via install link or push upgrade. Existing customers don't reinstall; they receive the upgrade as a new version.

The migration is mostly clean. These are the patterns that cause grief.

→ Hard-coded org references. Apex that references the packaging org's ID, named credentials pointing to the old org, or hard-coded API URLs. Sweep for these before extraction. → Sharing rules tied to packaging-org users. Sharing assumptions that worked in 1GP because your packaging org provisioned specific users may break in scratch orgs. → Test class assumptions. Unit tests that assumed packaging-org metadata existed by default. Update test setup to provision required data. → Custom labels and translations. Some 1GP packages have custom labels stored in ways that don't round-trip cleanly. Spot-check after extraction. → Component dependencies. Components that referenced unmanaged code in the packaging org. You either pull those into the package or restructure.

Nothing dramatic, if you do it right. The upgrade looks like any other version upgrade. Same namespace, same components, same install URL pattern. Data persists. Customizations on installed components persist.

Pro Tip

The thing customers do notice: if you've used the migration to split a monolithic 1GP package into multiple 2GP packages, they may install your modules separately going forward. Communicate that change clearly in release notes.

Three scenarios where waiting is fine.

→ You have no new feature roadmap planned. Migration is engineering work without immediate business return. → Your package depends on features only 1GP supports today. Check the gap before committing. → You're about to go through Salesforce's security review. Wait until you pass on 1GP, then migrate. Mid-review migrations add risk.

Otherwise, the longer you wait, the more drift between 1GP source organization and where 2GP wants you. Sooner is easier than later.

If you're building a new package, you skip the migration question entirely. No-code platforms default to 2GP and run Dev Hub, namespace registry, and CLI steps in the background. You describe the app, the platform generates the components and the 2GP package directly. See our guide on building a managed package without a Salesforce developer.

For existing 1GP customers considering migration: the same generation logic can produce the 2GP equivalent from your current package metadata, treating migration as a one-time generation step rather than an engineering project.

Use Salesforce's Package Migrations CLI to extract metadata from your 1GP package, set up Dev Hub and link your namespace, create a 2GP package, version it, and promote it (Salesforce 2GP Guide). Plan for 1 to 2 weeks of dedicated engineering work for a medium-complexity package.

No. The Package Migrations CLI preserves your existing namespace. Customer-installed components keep their API names. The namespace gets linked to your Dev Hub's Namespace Registry as part of setup.

No. Customers receive the 2GP version as a normal upgrade through their existing install path or via a push upgrade. Data persists. Component customizations persist.

1 to 2 weeks of dedicated engineering work for a medium-complexity package. Simple packages migrate in days. Complex packages with significant packaging-org dependencies, hard-coded references, or modular reorganization plans take longer.

Yes, for the upgrade path. Existing 1GP customers upgrade to the 2GP version cleanly. New customers install directly from the 2GP package. The two coexist while you transition.

No. Dev Hub is required for 2GP. Enabling it is one of the first steps in the migration sequence.

About the author. Sunny Chauhan is the founder and CEO of Appnigma AI, a no-code platform that generates Salesforce AppExchange-ready managed packages in 2GP by default. He works with ISV teams navigating the 1GP to 2GP transition.

1GP to 2GP managed package migration uses Salesforce's Package Migrations CLI to extract metadata, preserve the namespace, and continue package versioning. Plan for 1 to 2 weeks of engineering work, set up Dev Hub and namespace registry, audit hard-coded references, and test the upgrade in a scratch org before distributing. Customers receive the upgrade through their normal install path; no reinstall required.

• What is a managed package in Salesforce

• How to create a managed package in Salesforce

• How to upgrade a managed package in Salesforce

• How to build a managed package without a Salesforce developer

1/ Salesforce 2GP Developer Guide PDF (Package Migrations CLI, namespace registry) 2/ Salesforce ISVforce Guide (managed package upgrade paths) 3/ Practitioner migration write-ups (Hexaview, Softsquare)

What's the one piece of your current 1GP package you're most worried about during migration?