Using Yarn (an NPM alternative) on CircleCI
Yarn is an open-source package manager for JavaScript. The packages it installs can be cached. This can potentially speed up builds, but, more importantly, can reduce errors related to network connectivity.
Using Yarn in CircleCI
Yarn might already be installed in your execution environment if you are using the docker
executor. With Pre-built CircleCI Docker Images, the NodeJS image (circleci/node
) already has Yarn preinstalled. If you are using one of the other language images such as circleci/python
or circleci/ruby
, there are two image variants that will include Yarn as well as NodeJS. These would be the -node
and -node-browsers
image variants. For example, using the Docker image circleci/python:3-node
will give you a Python execution environment with Yarn and NodeJS installed.
If you’re using your own Docker image base or the macos
, windows
or machine
executors, you can install Yarn by following the official instructions from Yarn Docs. The Yarn Docs provide several installation methods depending on what machine executor you might be using. For example, you can install on any unix-like environment using the following curl command.
curl -o- -L https://yarnpkg.com/install.sh | bash
Caching
Yarn packages can be cached to improve CI build times.
Yarn 2.x added the ability to do Zero Installs; if you’re using Zero Installs, you shouldn’t need to do any special caching.
If you’re using Yarn 2.x without Zero Installs, you can do something like this:
#...
- restore_cache:
name: Restore Yarn Package Cache
keys:
- yarn-packages-{{ checksum "yarn.lock" }}
- run:
name: Install Dependencies
command: yarn install --immutable
- save_cache:
name: Save Yarn Package Cache
key: yarn-packages-{{ checksum "yarn.lock" }}
paths:
- .yarn/cache
- .yarn/unplugged
#...
An example for Yarn 1.x:
#...
- restore_cache:
name: Restore Yarn Package Cache
keys:
- yarn-packages-{{ checksum "yarn.lock" }}
- run:
name: Install Dependencies
command: yarn install --frozen-lockfile --cache-folder ~/.cache/yarn
- save_cache:
name: Save Yarn Package Cache
key: yarn-packages-{{ checksum "yarn.lock" }}
paths:
- ~/.cache/yarn
#...
See also
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.