Convert Your Managed 1GP Package to 2GP

Before you convert your managed 1GP package version, ensure your development environment is set up.

You need the latest version of Salesforce CLI installed, and the Dev Hub and second-generation managed packaging enabled in your PBO (Partner Business Org).

Package Conversion Steps

Run sf update to ensure you have the latest Salesforce CLI.
From your command line, navigate to the directory in which you plan to create your Salesforce DX project directory.
Create a Salesforce DX project. For example: sf project generate --name myconvertedpkg.
Authorize to your Dev Hub org.
sf org login web --set-default-dev-hub
Link the namespace of your managed 1GP to the Dev Hub in your Partner Business Org (PBO).
1. Log in to your Dev Hub org.
2. Follow the steps listed in Link a Namespace to a Dev Hub Org.
After you convert a package, it's associated with your Dev Hub org. The association between the Dev Hub org and your package can’t be changed. And you can't associate the package with a second, separate Dev Hub org. This means any subsequent package conversions you initiate for this package, must be associated with the Dev Hub org you specify the first time you convert a particular package.
If your package depends on standard value sets, create a seed metadata file. Then in step 7, when you run sf package convert, include the —-seed-metadata flag.

For details on setting up a seed metadata file, see Picklist Value Errors.

If your package has tests that depend on unpackaged metadata, add an unpackaged metadata directory to your sfdx-project.json file. To learn more about sfdx-project.json file, see Project Configuration File for a Second-Generation Managed Package.

Example:

1"packageDirectories": [
2    {
3        "path": "force-app",
4        "package": "TV_unl", 
5        "versionName": "ver 2.1",
6        "default": true, 
7        "unpackagedMetadata": {
8            "path": "my-unpackaged-directory"
9         }
10    }, 
11]

From the command line, navigate to the directory on your computer that contains your Salesforce DX project, then convert your package.
Example:
1sf package convert --installation-key mdpTest --package 033xxx --wait 20
To locate your 033 package ID, log in to your 1GP packaging org. From Setup, enter Package Manager in the Quick Find box, and then select Package Manager. Select the name of your managed package. After you navigate to the Package Detail page, inspect the URL in your browser’s address bar. The 15-character string in the URL that begins with 033 is your package ID.

If the package version you're converting is a patch version, you must include the --patch-version flag when you run the package convert command. Package versions follow a major.minor.patch.build number format. Any package version number that contains a non-zero patch number is a patch version. For example, 1.1.2 is a patch version, but 1.1.0 isn’t.
Before converting a patch version you must first convert the major.minor version of that package. Using the above example, you must convert package version 1.1.0 before converting patch version 1.1.2.

If your package depends on another package, specify that dependency in the sfdx-project.json file.

For details, see Create Dependencies Between Second-Generation Managed Packages

Note

What’s an Installation Key?

In the CLI command shown in step 7, an installation key with the value of mpdTest is specified. An installation key is a security key. By including this flag with the package conversion command, you’re setting a password and requiring that password whenever anyone installs the converted 2GP package. If you prefer not to require an installation key, specify --installation-key-bypass when you convert your package.

Congrats, Your Package is Converted

After you’ve completed steps 1-7, your 1GP package is converted to 2GP. You can test your package in a scratch org.

The converted package is a beta version. Before you migrate the package you must promote it to a managed-released version. See Get Ready to Promote and Release a Second-Generation Managed Package Version for details. To promote a package version to released, you must use the --code-coverage flag when converting the package version. The package must also meet the code coverage requirements.

Keep in mind that after you migrate subscribers to 2GP, all future upgrades to that package version for that subscriber must use a 2GP package version.

At this time, while 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 a 2GP, CLI-based development model. That functionality is coming soon.

First-Generation Managed Packaging Developer Guide

Convert Your Managed 1GP Package to 2GP