First-Generation Managed Packaging Developer Guide

First-Generation Managed Packages
Why Switch to Second-Generation Managed Packaging?
Move to 2GP: Migrate Your Managed Packages with Ease
About Package Conversion and Package Migration
Three Phases of Package Migration Development
Plan Your Package Migration
Before You Begin Package Migrations
Convert Your Managed 1GP Package to 2GP
Migrate Your Subscribers from 1GP to 2GP
Considerations for Package Migrations
Troubleshoot Package Conversion Failures
Register a Namespace for a First-Generation Managed Package
Create a First-Generation Managed Package Using a UI
Create a First-Generation Managed Package using Salesforce DX
Components Available in First-Generation Managed Packages
Behavior of Specific Metadata in First-Generation Managed Packages
Package and Test Your First-Generation Managed Package
Update Your First-Generation Managed Package
Publish Upgrades to First-Generation Managed Packages
Manage Licenses for Managed Packages
Manage Features in First-Generation Managed Packages
AppExchange App Analytics for First-Generation Managed Packages
Developing and Distributing Unmanaged Packages
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Considerations for Package Migrations

Review these limits and considerations for converting and migrating packages.
  1. Be sure you’ve reviewed Three Phases of Package Migration, and understand that as of the Summer '25 release, package migration is limited to phase one and two. Although you can convert and migrate subscribers to a 2GP package, there's no mechanism to move your package development from your 1GP packaging org to the 2GP, CLI-based development model.. This functionality is coming soon.
  2. Packages converted before June 15, 2025 can’t be promoted or migrated. Instead, run the convert command on your latest package version, and move forward with that package version.
  3. The daily package conversion limit is the same as your Dev Hub org’s scratch org allocation. See Scratch Org Allocations for Salesforce Partners for details.
  4. The convert command may fail on your first attempt to convert a package. If this happens, retry again in a few minutes. This issue is most likely to occur if you create a new package for testing purposes, and immediately try to convert that package version.
  5. The package conversion process performs limited validation when creating the managed 2GP package version.
    1. In some instances the limited validation could mask issues that would otherwise result in package conversion failure.
    2. You can expect to see cryptic error messages in certain scenarios. Please share those error messages with us so we can improve them.
  6. During migration, the managed 1GP package version installed in the target org has the same version number as the managed 2GP migration package version.
  7. Only package versions created using API version 57 (Spring ’23) or above, can be converted. To promote a package version, it must have been created using API version 64 (Summer ’25) or later.
  8. Large packages containing 20,000+ metadata files aren’t supported at this time.
  9. Packages containing Data Cloud metadata can’t be converted.