# An introduction to Yarn

> Learn modern Yarn: install it with Corepack, pin it per project, manage dependencies, run scripts, update packages, and choose an install mode.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2018-02-24 | Updated: 2026-07-18 | Topics: [DevTools](https://flaviocopes.com/tags/devtool/) | Canonical: https://flaviocopes.com/yarn/

Yarn is a package manager for JavaScript projects.

It reads dependencies and scripts from `package.json`, installs packages from registries such as npm, and records exact resolutions in `yarn.lock`.

Modern Yarn is significantly different from Yarn Classic. If an existing project contains a `yarn.lock` file and Yarn configuration, use the Yarn version declared by that project instead of silently upgrading it.

## Install Yarn with Corepack

Yarn recommends Corepack because it lets each project declare its package manager version.

Install Corepack, then enable its command shims:

```bash
npm install -g corepack
corepack enable
```

Some Node.js distributions already include Corepack, while others do not. The command above follows Yarn's current [installation guide](https://yarnpkg.com/getting-started/install).

Do not install modern Yarn globally with `npm install -g yarn`. A global Yarn version can change independently of your project and make installs less reproducible.

## Start a project

Initialize a new project with modern Yarn:

```bash
yarn init -2
```

In an existing project, pin the current stable Yarn release:

```bash
yarn set version stable
yarn install
```

The project records the package manager it expects. Commit the resulting `package.json`, `yarn.lock`, `.yarnrc.yml`, and any other Yarn-managed project files required by your configuration.

Run:

```bash
yarn --version
```

to see the active version.

## Install project dependencies

When you clone a project, install everything declared in `package.json`:

```bash
yarn install
```

Yarn updates or creates `yarn.lock`. Commit that lockfile so the team and CI resolve the same dependency tree.

In CI, prefer an immutable install:

```bash
yarn install --immutable
```

This fails if Yarn would need to modify the lockfile.

## Add dependencies

Add a runtime dependency:

```bash
yarn add lodash
```

Add a development dependency:

```bash
yarn add --dev vitest
```

Add a peer dependency:

```bash
yarn add --peer react
```

You can request an exact version or range:

```bash
yarn add lodash@^4
```

Check the [official `yarn add` reference](https://yarnpkg.com/cli/add) for supported protocols and flags.

Before adding an unfamiliar package, review its repository, maintenance history, dependencies, and install scripts. A package runs with your user's permissions when your tools execute it.

## Remove dependencies

Remove a package from the current workspace:

```bash
yarn remove lodash
```

Yarn updates both `package.json` and `yarn.lock`.

## Update dependencies

Upgrade one dependency across the project:

```bash
yarn up lodash
```

Upgrade matching dependencies interactively:

```bash
yarn up --interactive
```

Modern Yarn uses `yarn up`; old tutorials may show the Yarn Classic `yarn upgrade` command.

To update the Yarn release used by the project:

```bash
yarn set version stable
yarn install
```

Review dependency changes and run the project's tests before committing an update.

## Run scripts and package binaries

Given this `package.json`:

```json
{
  "scripts": {
    "dev": "vite",
    "test": "vitest run"
  }
}
```

run the scripts with:

```bash
yarn dev
yarn test
```

`yarn run test` is the explicit form.

To run a package once in a temporary environment, use `yarn dlx`:

```bash
yarn dlx create-vite
```

Use `dlx` for one-off commands, not as a replacement for a recorded project dependency. Yarn's [`dlx` documentation](https://yarnpkg.com/cli/dlx) explains why temporary commands are not reproducible installs.

## Understand why a package is installed

Use:

```bash
yarn why PACKAGE
```

This shows which workspace or dependency brought the package into the project.

Run the npm registry vulnerability audit with:

```bash
yarn npm audit
```

An audit report needs judgment: verify whether the vulnerable code is reachable and whether an upgrade introduces breaking changes.

## Plug'n'Play and `node_modules`

Modern Yarn uses Plug'n'Play by default. Instead of creating a traditional `node_modules` tree, it records dependency locations in a loader file.

If a tool does not work with Plug'n'Play, configure the familiar `node_modules` strategy in `.yarnrc.yml`:

```yaml
nodeLinker: node-modules
```

Then run:

```bash
yarn install
```

Yarn also supports a pnpm-style linker. The [install modes documentation](https://yarnpkg.com/features/linkers) explains the tradeoffs, and the [Plug'n'Play guide](https://yarnpkg.com/features/pnp) covers compatibility.

## Workspaces

Workspaces let one repository contain multiple related packages with one install and one lockfile.

They are useful for monorepos and for applications that share internal packages. Yarn can run commands across workspaces and use the `workspace:` protocol to link them together.

See the [Yarn workspaces guide](https://yarnpkg.com/features/workspaces) when a single-package project starts to grow.