# 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

```sh
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:

```sh
jup --version
```

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

```sh
npm install -g jup
```

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

## Enable the shims

Run:

```sh
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:

```sh
hash -r
```

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

```sh
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:

```sh
jup enable --exclude npm
```

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

```sh
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:

```sh
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):

```json
{
  "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:

```sh
pnpm install
```

Without shims, invoke the package manager through jup:

```sh
jup pnpm install
```

You can also override the project pin for one command:

```sh
jup yarn@4.9.0 --version
```

## Check the result

Run the offline diagnostic report:

```sh
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](./projects-and-workspaces) for exact versions, ranges, workspace behavior, and digest storage.