Migrating from Corepack

jup can be used with projects that already rely on Corepack. It understands:

• packageManager and devEngines.packageManager in package.json;
• .corepack.env;
• COREPACK_* environment variables;
• npm, pnpm, and Yarn command names; and
• Corepack's cache layout and common error text.

Every COREPACK_* variable also has a JUP_* spelling. If both are set, JUP_* takes priority.

This compatibility lets a repository keep its existing manifest while individual developers or CI jobs move from Corepack to jup. jup can also be installed under the corepack command name. It adds some files and behavior that standard Corepack does not provide, most notably .corepack.lock for range pins.

#Shim installation

jup installs shims in a per-user directory by default, so installation usually does not require administrator access. It also:

• includes npm unless you pass --exclude npm;
• refuses to overwrite a command from another installation unless you pass --force;
• records commands replaced with --force so jup disable can restore them; and
• reports when its shim directory is missing from PATH or another command takes precedence.

Corepack does not shim npm by default. Excluding npm gives you the closer Corepack behavior:

jup enable --exclude npm

#Manifest selection and edits

jup use and jup up stop their upward search at a workspace root rather than editing an unrelated ancestor. Add --here to edit only the current directory.

When both packageManager and devEngines.packageManager are present, jup checks them together and keeps their name and version constraints consistent. It also prints the path of every manifest it changes.

A packageManager field in a home-directory manifest can affect projects below it. jup info calls out the exact file that supplied the active declaration.

#Version resolution

jup does not select a prerelease unless the selector includes one or JUP_ENABLE_PRERELEASES=1 is set.

JUP_MINIMUM_RELEASE_AGE can exclude newly published releases from automatic selection. It does not override an exact pin or reject a version that is already cached.

For a package manager major that is newer than jup's built-in table, jup may use an entry point declared by the downloaded package rather than rejecting the major outright. The entry point still has to pass jup's package and path validation.

#Registry and network configuration

In addition to Corepack-compatible variables, jup reads the registry, authentication, and TLS entries it supports from .npmrc. It also handles standard proxy environment variables directly and applies request timeouts and retries.

JUP_REGISTRY_NPM, JUP_REGISTRY_PNPM, and JUP_REGISTRY_YARN let you mirror one manager without changing the registry used by the others.

#Verification rules

jup applies these restrictions when configuration comes from a repository:

• .corepack.env cannot disable verification, add trust keys, enable unsafe URLs, or provide registry credentials.
• A project .npmrc can select a registry but cannot provide credentials or certificate authorities.
• Registry credentials are sent only to the host and path they belong to.
• Tarball URLs and extracted paths are validated.
• Expired signing keys are rejected.
• Every downloaded artifact needs a pinned digest, valid signature, or registry digest unless unverified mode is explicitly enabled.

jup checks a project's digest even when the package manager is already in the cache. Direct Yarn Berry downloads may need a one-command bootstrap to create that digest; see Yarn Berry.

#Cache and execution

jup cache clean reports what it removed and leaves global fallback records intact unless --all is passed.

When jup starts a package manager, it places the resolved manager on the subprocess PATH. If a package script invokes pnpm again, for example, it receives the same pnpm version.

A global npm install is allowed even when the current project declares another manager.

#Compatibility output

Some help, usage, and error text still uses the name corepack. Existing scripts and CI jobs compare these strings, so jup preserves them for compatibility. If jup --help shows a command beginning with corepack, you can run the same example with jup.

The deprecated prepare and hydrate commands also remain available. Prefer pack and install -g in new scripts.

jup enables npm, pnpm, and Yarn by default. If a migration behaves differently than expected, run jup info to inspect the selected manifest, lockfile, registry, cache entry, and shim path, then continue with Troubleshooting.