Migrating from pnpm guide

Move a pnpm project to LPM CLI with workspace, catalog, override, and patch checks.

Use lpm migrate from the workspace root with package.json and pnpm-lock.yaml. Lockfile major versions 5, 6, and 9 are supported.

LPM CLI works with npm, private registries, and LPM.dev Registry. Install it with the installation guide.

For a monorepo, run migration from the workspace root. Member-directory migration fails before it changes files.

--rollback can still restore an older migration from the member directory that contains its recovery files.

Preview and convert

Commit the current project before migration. Keep the previous package manager available for rollback.

lpm migrate --dry-run
lpm migrate

Read the detected source, skipped entries, warnings, and workspace count before conversion.

If several supported lockfiles exist, the newest modification time selects the input. There is no source-selection flag.

Equal timestamps prefer bun.lockb, bun.lock, pnpm-lock.yaml, yarn.lock, then package-lock.json. Other lockfiles stay in place.

Migration writes a staging lockfile, configures .npmrc, installs dependencies online, and runs available root build and test scripts.

The online install resolves the manifest requirements again. Migration does not guarantee the exact versions from the previous lockfile.

At a workspace root, installation includes the workspace members. Verification runs the root scripts. Use your usual workspace checks too.

Workspace hooks that request the same install lock fail with a parent-installation conflict. Run those commands after migration.

The command is non-interactive. An existing lpm.lock requires --force. --yes does not imply that flag.

Review pnpm configuration

Workspace discovery combines package.json > workspaces with pnpm-workspace.yaml > packages. Overlapping members are deduplicated and exclusions apply.

The root YAML file can provide catalog, catalogs, and cleanupUnusedCatalogs. Matching manifest catalog entries and an explicit manifest cleanup setting take precedence.

Workspace installs use isolated layout by default. For a single package that must use isolated layout too:

package.json (additional field)

{
  "lpm": { "linker": "isolated" }
}

Existing .npmrc routing remains in place. Migration does not execute .pnpmfile.cjs. Translate required hook behavior into supported configuration before conversion.

Overrides, patches, and peer rules

Migration checks supported translations before it changes files:

pnpm field in `package.json`	Destination
`pnpm.overrides`	`lpm.overrides`
`pnpm.patchedDependencies`	`lpm.patchedDependencies` and lockfile patch records
`pnpm.peerDependencyRules`	`lpm.peerDependencyRules`

Conflicting rules, unsupported shapes, missing patch files, and unsafe patch paths stop conversion.

Patch files are copied into patches/. Original files remain, and retained pnpm.patchedDependencies paths point to the new copies.

Review both configurations before alternating package managers. Commit the copied patches with their manifest and lockfile records.

For compatibility diagnostics after conversion:

lpm doctor --all --json

See lpm migrate for translation details and workspaces for catalog behavior.

Separate conversion from installation

For a conversion without dependency installation, verification scripts, or registry configuration:

lpm migrate --no-install --skip-verify --no-npmrc --no-ci --json

--no-install alone does not skip verification. Migration has no dedicated lpm.json fields.

The staging lockfile cannot support an offline or frozen install. Complete a mutable online install first:

lpm install --no-frozen-lockfile

The explicit flag also works where CI=true normally selects frozen installation.

Check the result

Run the project's existing checks, then replay the new lockfile:

lpm run build
lpm run test
lpm install --frozen-lockfile

Replace these script names with the checks that your project defines. lpm run preserves custom test commands and their arguments.

After the store contains every required package, you can check offline replay:

lpm install --frozen-lockfile --offline

--offline controls package-network work. Root lifecycle scripts can still contact the network.

Dependency scripts stay denied by default. Review blocked scripts before authorizing packages that require installation builds.

Commit the migration

Inspect the complete diff and the resolved dependency versions:

git status --short
git diff

Commit lpm.lock and the intended manifest, configuration, patch, and CI changes.

Review .npmrc before committing it. Store credentials in environment variables or a user-level file, not in the repository.

Keep .backup files and .lpm-migrate-manifest.json together until you accept the migration. Keep these recovery files out of commits.

Remove the old manager's tracked lockfile only after the team accepts the migration. Do not delete recovery snapshots to clean the Git diff.

For CI, replace the install step with lpm ci. Review generated templates before enabling them.

Roll back or retry

lpm migrate --rollback

Rollback restores or removes files recorded in .lpm-migrate-manifest.json. Other install changes, node_modules, store contents, and script output remain.

After rollback, run the previous manager's install command to restore its dependency layout.

For an install or verification failure, fix the reported cause before retrying:

lpm migrate --force

Repeated migration retains the first recovery snapshots. Keep them until you no longer need rollback.

Migrating from pnpm