# 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:

```sh
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](./security#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](./troubleshooting).