Getting started

This guide installs jup, routes package manager commands through it, and pins a pnpm release in a project. The same steps work with npm and Yarn.

#Requirements

You need:

• Node.js 22.18 or newer;
• Git;
• pnpm, either installed already or made available through Corepack; and
• permission to install a global npm package.

jup is not published to npm yet, so the current version must be built from source.

#Install from source

git clone https://github.com/unjs/jup.git
cd jup
corepack enable
pnpm install
pnpm pack
npm install -g ./jup-0.0.0.tgz

The archive name comes from the version in package.json and may differ from jup-0.0.0.tgz. Use the filename printed by pnpm pack.

Confirm that the command is available:

jup --version

After jup is released to npm, the source build can be replaced with:

npm install -g jup

Do not use that command until an official release is announced.

#Enable the shims

Run:

jup enable

This creates commands for npm, npx, pnpm, pnpx, yarn, and yarnpkg. These small launcher files are called shims. They let jup inspect the current project before starting the package manager.

jup installs shims in a user-owned directory by default. If that directory is not on PATH, the command prints the line you need to add to your shell configuration. Open a new terminal after changing PATH. In an existing POSIX shell, you may also need:

hash -r

To install the shims somewhere else, provide a directory already on PATH:

jup enable --install-directory "$HOME/bin"

npm is included by default. This allows strict mode to reject npm install when a project declares pnpm or Yarn. To keep your existing npm command unchanged, exclude it:

jup enable --exclude npm

jup will not replace a command owned by another installation unless you explicitly allow it:

jup enable --force

When jup replaces a command, it records the original so that jup disable can restore it later.

#Pin a package manager

Change to the project you want to configure, then run:

jup use pnpm@11

jup finds the newest matching pnpm 11 release, downloads and verifies it, and writes the exact version to package.json. The result looks like this (digest shortened for the example):

{
  "packageManager": "pnpm@11.1.2+sha512.abc123..."
}

Commit the manifest change. Anyone who runs pnpm through jup, or through another compatible implementation that honors the pin, will use the same release and verify the same digest.

#Run pnpm normally

With the shims enabled, use the command you already know:

pnpm install

Without shims, invoke the package manager through jup:

jup pnpm install

You can also override the project pin for one command:

jup yarn@4.9.0 --version

#Check the result

Run the offline diagnostic report:

jup info

Check these sections:

• Project shows the manifest and pin jup found.
• Resolution shows the selected package manager version.
• Store shows whether that version is already cached.
• Shims shows where the launcher commands are installed and whether another command appears first on PATH.

Next, read Projects and workspaces for exact versions, ranges, workspace behavior, and digest storage.