yarn Documentation

1. Project Overview & Quickstart (yarnpkg/yarn) Copy Chapter

ℹ️ Important note Copy Chapter

This repository holds the sources for Yarn 1.x (latest version at the time of this writing being 1.22). New releases (at this time the 3.2.3, although we're currently working on our next major) are tracked on the yarnpkg/berry repository, this one here being mostly kept for historical purposes and the occasional hotfix we publish to make the migration from 1.x to later releases easier.

If you hit bugs or issues with Yarn 1.x, we strongly suggest you migrate to the latest release - at this point they have been maintained longer than 1.x, and many classes of problems have already been addressed there. By using the nodeLinker setting you'll also have the choice of how you want to install your packages: node_modules like npm, symlinks like pnpm, or manifest files via Yarn PnP.

Fast: Yarn caches every package it has downloaded, so it never needs to download the same package again. It also does almost everything concurrently to maximize resource utilization. This means even faster installs.

Reliable: Using a detailed but concise lockfile format and a deterministic algorithm for install operations, Yarn is able to guarantee that any installation that works on one system will work exactly the same on another system.

Secure: Yarn uses checksums to verify the integrity of every installed package before its code is executed.

Features Copy Chapter

• Offline Mode. If you've installed a package before, then you can install it again without an internet connection.
• Deterministic. The same dependencies will be installed in the same exact way on any machine, regardless of installation order.
• Network Performance. Yarn efficiently queues requests and avoids request waterfalls in order to maximize network utilization.
• Network Resilience. A single request that fails will not cause the entire installation to fail. Requests are automatically retried upon failure.
• Flat Mode. Yarn resolves mismatched versions of dependencies to a single version to avoid creating duplicates.
• More emojis. 🐈

Our supports Copy Chapter

[Gold sponsors](https://opencollective.com/yarnpkg) Copy Section

Installing Yarn Copy Chapter

Read the Installation Guide on our website for detailed instructions on how to install Yarn.

Using Yarn Copy Chapter

Read the Usage Guide on our website for detailed instructions on how to use Yarn.

Contributing to Yarn Copy Chapter

The 1.x codebase is fairly old and will only accept security fixes. For new features or bugfixes, please see our new repository and its contribution guide.

Prior art Copy Chapter

Yarn wouldn't exist if it wasn't for excellent prior art. Yarn has been inspired by the following projects:

• Bundler
• Cargo
• npm

Credits Copy Chapter

Thanks to Sam Holmes for donating the npm package name!

2. Official Technical Reference & Guides (yarnpkg/website) Copy Chapter

File: README.md Copy Chapter

Yarn Website [](https://app.netlify.com/sites/yarnpkg/deploys)

This repo contains the source code for the Yarn Classic (v1) website, available at https://classic.yarnpkg.com/. For the Yarn v2 site, see https://github.com/yarnpkg/berry/tree/master/packages/docusaurus

README in Japanese

In order to get started:

$ git clone [email protected]:yarnpkg/website.git yarn-website
$ cd yarn-website

You should ensure you have Yarn and Bundler installed:

$ gem install bundler

And then:

$ make

Or:

$ make install
$ make serve

On Windows, make is not available, so you need to execute bundle and jekyll directly:

bundle install
bundle exec jekyll serve --incremental

Special thanks to Netlify for powering the website.

File: lang/en/docs/cli/add.md Copy Chapter

id: docs_cli_add guide: docs_cli layout: guide additional_reading_tags: ["dependencies"] Copy Chapter

{% include vars.html %}

Installs a package and any packages that it depends on.

Adding dependencies Copy Section

In general, a package is simply a folder with code and a package.json file
that describes the contents. When you want to use another package, you first
need to add it to your dependencies. This means running yarn add [package-name]
to install it into your project.

This will also update your package.json and your yarn.lock so that other
developers working on the project will get the same dependencies as you when
they run yarn or yarn install.

Most packages will be installed from the npm registry
and referred to by simply their package name. For example, yarn add react
will install the react package from
the npm registry.

You can specify versions using one of these:

1. yarn add package-name installs the "latest" version of the package.
2. yarn add [email protected] installs a specific version of a package from
   the registry.
3. yarn add package-name@tag installs a specific
   "tag" (e.g. beta, next, or latest).

You can also specify packages from different locations:

1. yarn add package-name installs the package from the
   npm registry unless you have specified another one
   in your package.json.
2. yarn add file:/path/to/local/folder installs a package that is on your
   local file system. This is useful to test out other packages of yours that
   haven't been published to the registry.
3. yarn add file:/path/to/local/tarball.tgz installs a package from a gzipped
   tarball which could be used to share a package before publishing it.
4. yarn add link:/path/to/local/folder installs a symlink to a package that is
   on your local file system. This is useful to develop related packages in
   monorepo environments.
5. yarn add <git remote url> installs a package from a remote git repository.
6. yarn add <git remote url># installs a package from a remote
   git repository at specific git branch, git commit or git tag.
7. yarn add https://my-project.org/package.tgz installs a package from a
   remote gzipped tarball.

Caveats Copy Section

If you have used a package manager like npm previously, you may be looking for
how to add global dependencies.

For the vast majority of packages it is considered a bad practice to have
global dependencies because they are implicit. It is much better to add
all of your dependencies locally so that they are explicit and anyone else
using your project gets the same set of dependencies.

If you are trying to use a CLI tool that has a bin you can access these in
your ./node_modules/.bin directory. You can also use the
global command:

yarn global add

Commands Copy Section

`yarn add `

This will install one or more packages in your
dependencies.

`yarn add [--dev/-D]`

Using --dev or -D will install one or more packages in your
devDependencies.

`yarn add [--peer/-P]`

Using --peer or -P will install one or more packages in your
peerDependencies.

`yarn add [--optional/-O]`

Using --optional or -O will install one or more packages in your
optionalDependencies.

`yarn add [--exact/-E]`

Using --exact or -E installs the packages as exact versions. The default is
to use the most recent release with the same major version. For example,
yarn add [email protected] would accept version 1.9.1, but
yarn add [email protected] --exact would only accept version 1.2.3.

`yarn add [--tilde/-T]`

Using --tilde or -T installs the most recent release of the packages that
have the same minor version. The default is to use the most recent release with
the same major version. For example, yarn add [email protected] --tilde would accept
1.2.9 but not 1.3.0.

`yarn add [--ignore-workspace-root-check/-W]`

Using --ignore-workspace-root-check or -W allows a package to be installed
at the workspaces root. This tends not to be desired behaviour, as
dependencies are generally expected to be part of a workspace. For example
yarn add lerna --ignore-workspace-root-check --dev at the workspaces root
would allow lerna to be used within the scripts of the root package.json.

`yarn add @npm:`

This will install a package under a custom alias. Aliasing, allows multiple
versions of the same dependency to be installed, each referenced via the
alias-package name given. For example, yarn add my-foo@npm:foo
will install the package foo (at the latest version) in your
dependencies
under the specified alias my-foo. Also, yarn add my-foo@npm:[email protected] allows
a specific version of foo to be installed.

`yarn add --audit`

Checks for known security issues with the installed packages. A count of found issues will be added to the output. Use the yarn audit command for additional details.

File: lang/en/docs/cli/audit.md Copy Chapter

id: docs_cli_audit guide: docs_cli layout: guide Copy Chapter

{% include vars.html %}

Perform a vulnerability audit against the installed packages.

`yarn audit [--verbose] [--json] [--level] [--groups]`

Checks for known security issues with the installed packages. The output is a list of known issues.

You must be online to perform the audit. The audit will be skipped if the --offline general flag is specified.

The command will exit with a non-0 exit code if there are issues of any severity found. The exit code will be a mask of the severities.

• 1 for INFO
• 2 for LOW
• 4 for MODERATE
• 8 for HIGH
• 16 for CRITICAL

For example, if only INFO and MODERATE vulnerabilities were found, then the exit code will be 1 + 4 = 5

For scripting purposes, yarn audit also supports the --json flag, which will output the details for the issues in JSON-lines format (one JSON object per line) instead of plain text.

If you are experiencing issues with the audit command please run with the --verbose flag, which will output the JSON data that yarn sends to the npm registry as well as the response data, and open an issue on GitHub that includes this data.

Commands Copy Section

`yarn audit [--level info|low|moderate|high|critical]`

Applying the level flag will limit the audit table to vulnerabilities of the corresponding level and above. It will not affect the exit code of the command.

`yarn audit [--groups group_name ...]`

Applying the groups flag will limit the audit table to vulnerabilities of the corresponding dependency groups (e.g dependencies, devDependencies).

Example for auditing only one group:

$ yarn audit --groups dependencies

Or multiple groups:

$ yarn audit --groups "dependencies devDependencies"

File: lang/en/docs/cli/autoclean.md Copy Chapter

id: docs_cli_autoclean guide: docs_cli layout: guide Copy Chapter

Cleans and removes unnecessary files from package dependencies.

`yarn autoclean [-I/--init] [-F/--force]`

The autoclean command frees up space by removing unnecessary files and folders from dependencies. It reduces the number of files in your project's node_modules folder which is useful in an environment where packages are checked into version control directly.

Note: This command is considered for advanced use cases only. Unless you are experiencing issues with the amount of files that are installed as part of node_modules it is not recommended to use this command. It will permanently delete files in node_modules which could cause packages to stop working.

Autoclean functionality is disabled by default. To enable it, manually create a .yarnclean file, or run yarn autoclean --init to create the file with default entries. The .yarnclean file should be added to version control.

When the .yarnclean file exists in a package, autoclean functionality will be enabled. The clean will be performed:

• After an install
• After an add
• If yarn autoclean --force is run

The clean is performed by reading each line of the .yarnclean file and using each as a glob pattern of files to delete.

Options:

-I/--init : Creates the .yarnclean file if it does not exist, and adds the default entries. This file should then be reviewed and edited to customize which files will be cleaned. If the file already exists, it will not be overwritten.

-F/--force : If a .yarnclean file exists, run the clean process. If the file does not exist, do nothing.

Defaults:

When the yarn autoclean --init command is used to create a .yarnclean file, it will be pre-populated with a set of default items
for deletion. This default list is a guess at what is likely not needed. It is impossible to predict all directories and files that
are actually unnecessary for all existing and future NPM packages, so this default list may cause a package to no longer work.

It is highly recommended that you manually review the default entries in .yarnclean and customize them to fit your needs.

If you discover the autoclean process is deleting files that are needed for a package to work properly, then you should remove the
corresponding entry from the .yarnclean file.

Example:

You decide all YAML and Markdown files in all your dependencies installed in node_modules can be safely deleted. You make a .yarnclean file containing:

*.yaml
*.md

You then run yarn install or yarn autoclean --force. The clean process will delete all *.yaml and *.md files within node_modules/ recursively (including nested transitive dependencies).

File: lang/en/docs/cli/bin.md Copy Chapter

id: docs_cli_bin guide: docs_cli layout: guide Copy Chapter

{% include vars.html %}

Displays the location of the yarn bin folder.

`yarn bin []`

• yarn bin will print the folder where yarn will install executable files for your package. An example of an executable may be a script that you have defined for your package that can be executed via yarn run.

Example:

$ yarn bin
/home/emillumine/Code/Funkwhale/funkwhale/front/node_modules/.bin

• yarn bin <executable> will print the path to the executable file.

Example:

$ yarn bin gettext-compile
/home/emillumine/Code/Funkwhale/funkwhale/front/node_modules/.bin/gettext-compile

File: lang/en/docs/cli/cache.md Copy Chapter

id: docs_cli_cache guide: docs_cli layout: guide Copy Chapter

`yarn cache list [--pattern]`

Yarn stores every package in a global cache in your user directory on the file
system. yarn cache list will print out every cached package.

yarn cache list --pattern will print out every cached package that matches the pattern provided.

Examples:

yarn cache list --pattern gulp
yarn cache list --pattern "gulp|grunt"
yarn cache list --pattern "gulp-(match|newer)"

`yarn cache dir`

Running yarn cache dir will print out the path where yarn's global cache is currently stored.

`yarn cache clean []`

Running this command will clear the global cache. It will be populated again the
next time yarn or yarn install is run. Additionally, you can specify one or more packages that you want to clean.

Change the cache path for yarn Copy Section

Set cache-folder config value to configure the cache directory.

yarn config set cache-folder

You can also specify the cache directory by flag --cache-folder:

yarn <command> --cache-folder

You can also specify the cache directory by environment variable YARN_CACHE_FOLDER:

YARN_CACHE_FOLDER= yarn <command>

Yarn will also respect cache= in .npmrc for compatibility with npm.

File: lang/en/docs/cli/check.md Copy Chapter

id: docs_cli_check guide: docs_cli layout: guide Copy Chapter

`yarn check`

Verifies that versions of the package dependencies in the current project's package.json match those in yarn's lock file.

NOTE: The command yarn check has been historically buggy and undermaintained and, as such, has been deprecated and will be removed in Yarn 2.0. You should use yarn install --check-files instead.

The switches --integrity and --verify-tree are mutually exclusive.

`yarn check --integrity`

Verifies that versions and hashed values of the package contents in the project's package.json match those in yarn's lock file. This helps to verify that the package dependencies have not been altered.

`yarn check --verify-tree`

Recursively verifies that the dependencies in package.json are present in node_modules and have the right version. This check does not consider yarn.lock.

File: lang/en/docs/cli/config.md Copy Chapter

id: docs_cli_config guide: docs_cli layout: guide Copy Chapter

Manages the yarn configuration files.

`yarn config set [-g|--global]`

Sets the config key to a certain value.

Example:

$ yarn config set init-license BSD-2-Clause
yarn config vx.x.x
success Set "init-license" to "BSD-2-Clause".
✨  Done in 0.05s.

`yarn config get `

Echoes the value for a given key to stdout.

Example:

$ yarn config get init-license
BSD-2-Clause

`yarn config delete `

Deletes a given key from the config.

Example:

$ yarn config delete test-key
yarn config vx.x.x
success Deleted "test-key".
✨  Done in 0.06s.

`yarn config list`

Displays the current configuration.

Example:

$ yarn config list
yarn config vx.x.x
info yarn config
{ 'version-tag-prefix': 'v',
  'version-git-tag': true,
  'version-git-sign': false,
  'version-git-message': 'v%s',
  'init-version': '1.0.0',
  'init-license': 'MIT',
  'save-prefix': '^',
  'ignore-scripts': false,
  'ignore-optional': true,
  registry: 'https://registry.yarnpkg.com',
  'user-agent': 'yarn/0.15.0 npm/? node/v6.2.1 darwin x64' }
info npm config
{ registry: 'https://registry.npmjs.org/',
  '//localhost:4873/:_authToken': 'some-auth-token' }
✨  Done in 0.05s.

File: lang/en/docs/cli/create.md Copy Chapter

id: docs_cli_create guide: docs_cli layout: guide Copy Chapter

{% include vars.html %}

Creates new projects from any create-* starter kits.

`yarn create []`

This command is a shorthand that helps you do two things at once:

• Install create-<starter-kit-package> globally, or update the package to the
  latest version if it already exists
• Run the create-<starter-kit-package> executable located in the bin field of the starter kit’s package.json,
  forwarding any <args> to it

For example, yarn create react-app my-app is equivalent to:

$ yarn global add create-react-app
$ create-react-app my-app

For more information, check out the relevant blog entry.

File: lang/en/docs/cli/dedupe.md Copy Chapter

id: docs_cli_dedupe guide: docs_cli layout: guide Copy Chapter

{% include vars.html %}

The dedupe command isn't necessary. yarn install will already dedupe.