Yarnrc files (named this way because they must be called .yarnrc.yml) are the one place where you'll be able to configure Yarn's internal settings. While Yarn will automatically find them in the parent directories, they should usually be kept at the root of your project (often your repository). Starting from the v2, they must be written in valid Yaml and have the right extension (simply calling your file .yarnrc won't do).

Environment variables can be accessed from setting definitions by using the ${NAME} syntax when defining the values. By default Yarn will require the variables to be present, but this can be turned off by using either ${NAME-fallback} (which will return fallback if NAME isn't set) or ${NAME:-fallback} (which will return fallback if NAME isn't set, or is an empty string).

Finally, note that most settings can also be defined through environment variables (at least for the simpler ones; arrays and objects aren't supported yet). To do this, just prefix the names and write them in snake case: YARN_CACHE_FOLDER will set the cache folder (such values will overwrite any that might have been defined in the RC files - use them sparingly).

Path where the downloaded packages are stored on your system.

They'll be normalized, compressed, and saved under the form of zip archives with standardized names. The cache is deemed to be relatively safe to be shared by multiple projects, even when multiple Yarn instances run at the same time on different projects. For setting a global cache folder, you should use enableGlobalCache instead.

List of git refs against which Yarn will compare your branch when it needs to detect changes.

Supports git branches, tags, and commits. The default configuration will compare against main and master.

# Compare changes against the main branch only.
changesetBaseRefs:
  - "main"
  - "origin/main"

# Compare changes against both stable branch names used by the project.
changesetBaseRefs:
  - "main"
  - "origin/main"
  - "master"
  - "origin/master"

Amount of git clone operations that Yarn will run at the same time.

We by default limit it to 2 concurrent clone operations.

Compression level employed for zip archives

Possible values go from 0 ("no compression, faster") to 9 ("heavy compression, slower").

Default prefix used in semver ranges created by yarn add and similar commands.

Possible values are caret (the default), tilde, and exact; the symbolic aliases ^, ~, =, *, and the empty string are also accepted.

Folder where the versioning files are stored.

Define whether constraints should run on every install.

If true, Yarn will run your constraints right after finishing its installs. This may help decrease the feedback loop delay by catching errors long before your CI would even report them.

Define whether the cache should be shared between all local projects.

If true (the default), Yarn will store the cache files into a folder located within globalFolder instead of respecting cacheFolder.

Define whether Yarn should attempt to check for malicious changes.

If true, Yarn will query the remote registries to validate that the lockfile content matches the remote information. These checks make installs slower, so you should only run them on branches managed by users outside your circle of trust.

Yarn will automatically enable the hardened mode on GitHub pull requests from public repository. Should you want to disable it, explicitly set it to false in your yarnrc file.

Define whether to allow adding/removing files from the cache or not.

If true, Yarn will refuse to change the cache in any way, whether it would add files or remove them, and will abort installs instead of letting that happen.

Define whether to allow adding/removing entries from the lockfile or not.

If true (the default on CI), Yarn will refuse to change the lockfile in any way, whether it would add new entries or remove them. Other files can be added to the checklist via the immutablePatterns setting.

Define whether to mirror local cache entries into the global cache or not.

If true (the default), Yarn will use the global folder as indirection between the network and the actual cache. This is only useful if enableGlobalCache is explicitly set to false, as otherwise the cache entries are persisted to the global cache no matter what.

Define whether remote network requests are allowed or not.

If false, Yarn will never make any request to the network by itself, and will throw an exception rather than let it happen. It's a very useful setting for CI, which typically want to make sure they aren't loading their dependencies from the network by mistake.

Define whether animated progress bars should be shown or not.

If true (the default outside of CI environments), Yarn will show progress bars for long-running events.

Define whether to run postinstall scripts or not.

If false, Yarn will not execute the postinstall scripts from third-party packages when installing the project (workspaces will still see their postinstall scripts evaluated, as they're assumed to be safe if you're running an install within them).

Note that you also have the ability to disable scripts on a per-package basis using dependenciesMeta, or to re-enable a specific script by combining enableScripts and dependenciesMeta.

Define whether SSL errors should fail requests or not.

If false, SSL certificate errors will be ignored

Define whether to print the time spent running each sub-step or not.

If false, Yarn will not print the time spent running each sub-step when running various commands. This is only needed for testing purposes, when you want each execution to have exactly the same output as the previous ones.

Define whether pure semver ranges should allow workspace resolution or not.

If false, Yarn won't link workspaces just because their versions happen to match a semver range. Disabling this setting will require all workspaces to reference one another using the explicit workspace: protocol.

This setting is usually only needed when your project needs to use the published version in order to build the new one (that's for example what happens with Babel, which depends on the latest stable release to build the future ones).

Path where all files global to the system will be stored.

Various files we be stored there: global cache, metadata cache, ...

Proxy to use when making an HTTP request.

Amount of time to wait in seconds before retrying a failed HTTP request.

Amount of time to wait in milliseconds before cancelling pending HTTP requests.

Path to a file containing one or multiple Certificate Authority signing certificates.

Path to a file containing a certificate chain in PEM format.

Path to a file containing a private key in PEM format.

Define a proxy to use when making an HTTPS request.

Array of file patterns whose content won't be allowed to change if enableImmutableInstalls is set.

# Protect PnP loader files during immutable installs.
immutablePatterns:
  - "**/.pnp.*"

# Protect both generated install artifacts and checked-in package archives.
immutablePatterns:
  - ".pnp.cjs"
  - ".pnp.loader.mjs"
  - ".yarn/cache/**"

Scope used when creating packages via the init command.

Array of .env files which will get injected into any subprocess spawned by Yarn.

By default Yarn will automatically inject the variables stored in the .env.yarn file, but you can use this setting to change this behavior.

Note that adding a question mark at the end of the path will silence the error Yarn would throw should the file be missing, which may come in handy when declaring local configuration files.

# Load the default Yarn env file and fail if it is missing.
injectEnvironmentFiles:
  - ".env.yarn"

# Load one shared file and one optional local override.
injectEnvironmentFiles:
  - ".env.yarn"
  - ".env.local?"

Alter the log levels for emitted messages.

This can be used to hide specific messages, or instead make them more prominent. Rules defined there accept filtering messages by exact text or glob pattern.

# Hide all messages matching a glob pattern.
logFilters:
  -
    pattern: "optional dependency * skipped"
    level: "discard"

# Upgrade one exact log message to an error.
logFilters:
  -
    text: "Package build failed"
    level: "error"

Amount of HTTP requests that are allowed to run at the same time.

We default to 100 concurrent requests, but it may be required to limit it even more when working behind proxies that can't handle large amounts of traffic.

Additional network settings, per hostname

# Disable network access for one host pattern.
networkSettings:
  "*.example.com":
    enableNetwork: false

# Use a custom CA certificate for an internal registry.
networkSettings:
  "registry.corp.example":
    httpsCaFilePath: "./certs/corp-ca.pem"

Highest point where packages can be hoisted.

Replacement of the former nohoist setting. Possible values are:

• If none (the default), packages are hoisted as per the usual rules.
• If workspaces, packages won't be hoisted past the workspace that depends on them.
• If dependencies, transitive dependencies also won't be hoisted past your direct dependencies.

This setting can be overridden on a per-workspace basis using the installConfig.hoistingLimits field.

Define whether workspaces are allowed to require themselves.

If false, Yarn won't create self-referencing symlinks when using nodeLinker: node-modules. This setting can be overridden on a per-workspace basis using the installConfig.selfReferences field.

Define how to copy files to their target destination.

Possible values are:

• If classic, regular copy or clone operations are performed.
• If hardlinks-global, hardlinks to a global content-addressable store will be used.
• If hardlinks-local, hardlinks will only be created between similar packages from the same project.

For compatibility with the ecosystem, the default is classic.

Define how Node packages should be installed.

Yarn supports three ways to install your project's dependencies, based on the nodeLinker setting. Possible values are:

• If pnp, a single Node.js loader file will be generated.
• If pnpm, a node-modules will be created using symlinks and hardlinks to a global content-addressable store.
• If node-modules, a regular node_modules folder just like in Yarn Classic or npm will be created.

# Use Plug'n'Play installs.
nodeLinker: "pnp"

# Use a traditional node_modules install.
nodeLinker: "node-modules"

Path where the pnpm store will be stored

By default, the store is stored in the node_modules/.pnpm of the project. Sometimes in CI scenario's it is convenient to store this in a different location so it can be cached and reused.

# Use the default virtual store inside node_modules.
pnpmStoreFolder: "node_modules/.pnpm"

# Move the virtual store to a cacheable project folder.
pnpmStoreFolder: ".cache/.pnpm"

Define whether to use junctions or symlinks when creating links on Windows.

Possible values are:

• If junctions, Yarn will use Windows junctions when linking workspaces into node_modules directories, which are always absolute paths.
• If symlinks, Yarn will use symlinks, which will use relative paths, and is consistent with Yarn's behavior on non-Windows platforms.

Define whether to always send authentication credentials when querying the npm registry.

If true, authentication credentials will always be sent when sending requests to the registries. This shouldn't be needed unless you configured the registry to reference a private npm mirror.

Define the registry to use when auditing dependencies.

If not explicitly set, the value of npmRegistryServer will be used.

Define the authentication credentials to use by default when accessing your registries.

Replacement of the former _auth setting. Because it requires storing unencrypted values in your configuration, npmAuthToken should be preferred when possible.

Define the authentication token to use by default when accessing your registries.

Replacement of the former _authToken settings. If you're using npmScopes to define multiple registries, the npmRegistries dictionary allows you to override these credentials on a per-registry basis.

Define the default access to use when publishing packages to the npm registry.

Valid values are public and restricted, but restricted usually requires to register for a paid plan (this is up to the registry you use). Can be overridden on a per-package basis using the publishConfig.access field.

Define whether to attach a provenance statement when publishing packages to the npm registry.

If true, Yarn will generate and publish the provenance information when publishing packages. Can be overridden on a per-package basis using the publishConfig.provenance field.

Array of package name glob patterns to exclude from yarn npm audit.

# Exclude one package from audit reports.
npmAuditExcludePackages:
  - "known_insecure_package"

# Exclude a family of internal test fixtures.
npmAuditExcludePackages:
  - "@example/fixture-*"
  - "legacy-test-helper"

Array of advisory ID glob patterns to ignore from yarn npm audit results.

# Ignore a single advisory ID.
npmAuditIgnoreAdvisories:
  - "1234567"

# Ignore a short-term allowlist of advisory IDs while patches are pending.
npmAuditIgnoreAdvisories:
  - "1234567"
  - "GHSA-xxxx-yyyy-zzzz"

Define the registry to use when pushing packages.

If not explicitly set, the value of npmRegistryServer will be used. Overridden by publishConfig.registry.

Per-registry configurations.

# Configure authentication for the public npm registry.
npmRegistries:
  "//registry.npmjs.org":
    npmAuthToken: "${NPM_TOKEN}"

# Always send auth for a private registry.
npmRegistries:
  "//npm.pkg.github.com":
    npmAlwaysAuth: true
    npmAuthToken: "${GITHUB_TOKEN}"

Define the registry to use when fetching packages.

Should you want to define different registries for different scopes, see npmScopes. To define the authentication scheme for your servers, see npmAuthToken. The url must use HTTPS by default, but this can be changed by adding it to the unsafeHttpWhitelist.

Per-scope registry configurations.

# Route one scope to a GitHub Packages registry.
npmScopes:
  my-company:
    npmRegistryServer: "https://npm.pkg.github.com"
    npmAuthToken: "${GITHUB_TOKEN}"

# Use a different registry only when publishing a scope.
npmScopes:
  my-company:
    npmPublishRegistry: "https://npm.pkg.github.com"
    npmRegistryServer: "https://registry.npmjs.org"

Extend the package definitions of your dependencies; useful to fix third-party issues.

Some packages may have been specified incorrectly with regard to their dependencies - for example with one dependency being missing, causing Yarn to refuse it the access. The packageExtensions fields offer a way to extend the existing package definitions with additional information. If you use it, consider sending a PR upstream and contributing your extension to the plugin-compat database.

Note: This field is made to add dependencies; if you need to rewrite existing ones, prefer the resolutions field instead.

# Add a missing regular dependency to a third-party package.
packageExtensions:
  "some-package@*":
    dependencies:
      lodash: "^4.17.21"

# Declare an optional peer dependency for a package that forgot its metadata.
packageExtensions:
  "webpack-plugin-example@*":
    peerDependencies:
      webpack: "*"
    peerDependenciesMeta:
      webpack:
        optional: true

Folder where patch files will be written to.

Define whether to store the PnP data in the generated file or not.

If false, Yarn will generate an additional .pnp.data.json file.

Define whether to allow packages to rely on the builtin PnP fallback mechanism.

Possible values are:

• If all, all packages can access dependencies made available in the fallback.
• If dependencies-only (the default), dependencies will have access to them but not your workspaces.
• If none, no packages will have access to them.

Array of file glob patterns that should be forced to use the default CommonJS resolution.

Files matching those locations will not be covered by PnP and will use the regular Node.js resolution algorithm. Typically only needed if you have subprojects that aren't yet part of your workspace tree.

# Exclude one legacy subproject from Plug'n'Play resolution.
pnpIgnorePatterns:
  - "./legacy/*"

# Exclude multiple generated package folders.
pnpIgnorePatterns:
  - "./examples/*"
  - "./fixtures/*"

String prepended to the generated PnP loader.

Path where unplugged packages are stored.

While Yarn attempts to reference and load packages directly from their zip archives, it may not always be possible. In those cases, Yarn will extract the files to the unplugged folder.

Define whether to use deferred versioning by default or not.

If true, deferred versioning by default when running the yarn version family of commands.

Define whether to use interactive prompts by default or not.

If true, Yarn will ask for your guidance when some actions would be improved by being disambiguated. Enabling this setting also unlocks some features (for example the yarn add command will suggest to reuse the same dependencies as other workspaces if pertinent).

Define whether to reuse most common dependency ranges or not when adding dependencies to a package.

If true, yarn add will attempt to reuse the most common dependency range in other workspaces.

Define whether to truncate lines that would go beyond the size of the terminal or not.

If true, Yarn will truncate lines that would go beyond the size of the terminal. If progress bars are disabled, lines will never be truncated.

Systems for which Yarn should install packages.

# Install packages for the current platform plus Linux x64.
supportedArchitectures:
  os:
    - "current"
    - "linux"
  cpu:
    - "current"
    - "x64"
  libc:
    - "current"
    - "glibc"

# Pre-resolve common macOS and Linux variants for a mixed team.
supportedArchitectures:
  os:
    - "darwin"
    - "linux"
  cpu:
    - "x64"
    - "arm64"
  libc:
    - "glibc"
    - "musl"

List of operating systems to cover.

List of CPU architectures to cover.

See https://nodejs.org/docs/latest/api/process.html#processarch for the architectures supported by Node.js

The list of standard C libraries to cover.

Define whether to automatically install @types dependencies.

If true, Yarn will automatically add @types dependencies when running yarn add with packages that don't provide their own typings (as reported by the Algolia npm database). This behavior is enabled by default if you have a tsconfig.json file at the root of your project, or in your current workspace.

Array of git repository URL patterns that are allowed to be fetched.

Git dependencies are rejected unless their repository URL matches one of these glob patterns. The default empty list blocks all git dependencies.

# Allow every repository from one GitHub organization.
approvedGitRepositories:
  - "https://github.com/yarnpkg/*"

# Allow a single SSH repository.
approvedGitRepositories:
  - "git@github.com:my-company/internal-package.git"

Maximum number of output lines kept in memory per daemon task.

Long-running daemon tasks keep a bounded output buffer so recent logs remain available without unbounded memory growth.

# Keep only a short tail for very chatty tasks.
daemonOutputBufferMaxLines: 200

# Keep a larger in-memory history while debugging task output.
daemonOutputBufferMaxLines: 5000

Maximum number of completed daemon tasks kept in memory.

Once this limit is reached, older completed or failed daemon tasks may be discarded from the daemon's in-memory history.

# Keep a smaller history on memory-constrained machines.
daemonMaxClosedTasks: 25

# Keep more completed tasks available for inspection.
daemonMaxClosedTasks: 250

Default warm-up period for long-lived daemon tasks.

After a long-lived task starts, dependents are unblocked once this duration elapses.

# Use a shorter warm-up for tasks that become ready quickly.
daemonDefaultWarmupPeriod: "500ms"

# Use a longer warm-up for services that take time to become ready.
daemonDefaultWarmupPeriod: "10s"

Define whether Yarn should automatically add @types packages.

When enabled, Yarn may add matching @types/* packages when adding dependencies that don't ship their own TypeScript declarations. This setting is also available through the tsEnableAutoTypes alias.

# Enable automatic type acquisition explicitly.
enableAutoTypes: true

# Disable automatic type acquisition for projects that manage types manually.
enableAutoTypes: false

Define whether the cache clean command is allowed to remove cache entries.

If false, cache clean operations won't remove entries from the cache.

# Prevent cache clean operations in shared environments.
enableCacheClean: false

# Allow cache clean operations.
enableCacheClean: true

Define whether unused packages should be removed from the local cache after installs.

When enabled, Yarn can remove unused entries from the project-local cache after each install.

# Keep stale local cache entries around for manual inspection.
enableLocalCacheCleanup: false

# Clean unused local cache entries after installs.
enableLocalCacheCleanup: true

Define whether migration mode should be enabled.

Migration mode changes various settings to make migration easier. It is usually applied automatically by Yarn Switch when necessary rather than set manually.

# Enable migration compatibility behavior for a project.
enableMigrationMode: true

# Use the regular behavior once migration is complete.
enableMigrationMode: false

Define whether Yarn should enforce unsafe HTTP requests over HTTPS.

This setting is intended for controlled environments that deliberately need to force unsafe HTTP behavior.

# Keep HTTPS enforcement enabled.
enforceUnsafeHttp: false

# Force unsafe HTTP in a controlled test environment.
enforceUnsafeHttp: true

URL used to download Node.js distributions.

Yarn uses this endpoint when resolving managed Node.js binaries.

# Use the official Node.js distribution endpoint.
nodeDistUrl: "https://nodejs.org/dist"

# Use an internal mirror for Node.js distributions.
nodeDistUrl: "https://artifacts.example.com/nodejs/dist"

Minimum package version age required before installation.

Versions newer than this duration won't be considered for installation unless they are preapproved. This can reduce exposure to newly-published supply-chain incidents.

# Require packages to be at least one day old.
npmMinimalAgeGate: "1d"

# Use a shorter gate for fast-moving internal projects.
npmMinimalAgeGate: "1h"

Package descriptors that bypass the minimum age gate.

Use this list for packages you trust or that must be installed immediately despite npmMinimalAgeGate.

# Preapprove one package range.
npmPreapprovedPackages:
  - "typescript@^5.0.0"

# Preapprove multiple trusted packages.
npmPreapprovedPackages:
  - "@my-scope/*@*"
  - "eslint@^9.0.0"

Package patterns hoisted to node_modules/.pnpm/node_modules.

By default all packages are hoisted into the hidden modules directory inside the pnpm virtual store. Use an empty array to disable this hoisting.

# Disable hidden-store hoisting.
pnpmHoistPatterns: []

# Hoist every package plus a scoped package family.
pnpmHoistPatterns:
  - "*"
  - "@babel/*"

Package patterns hoisted to the root node_modules directory.

Unlike pnpmHoistPatterns, this setting hoists matching packages to the public root node_modules directory.

# Expose selected tooling packages at the project root.
pnpmPublicHoistPatterns:
  - "eslint"
  - "prettier"

# Disable public hoisting.
pnpmPublicHoistPatterns: []

Timeout before a network request is considered slow.

The value is expressed in milliseconds and controls when Yarn reports a network request as slow.

# Report slow requests after five seconds.
slowNetworkTimeout: 5000

# Use a more patient threshold on slow networks.
slowNetworkTimeout: 30000

Configuration of resolution islands.

Each island resolves its transitive dependencies in isolation using a constraint solver, producing at most one version of each package per island.

# Resolve a subset of workspaces through the node-modules linker.
unstableIslands:
  web:
    workspaces:
      - "@acme/web-*"
    linker: "node-modules"

# Resolve Python workspaces through the venv linker.
unstableIslands:
  python:
    workspaces:
      - "@acme/py-*"
    linker: "venv"

Per-profile dependencies that can be applied to workspaces.

Workspace profiles let you define reusable dev dependency sets. Workspaces can inherit them through their manifest extends field, and the default profile is applied automatically.

# Apply a managed Node.js version to every workspace.
workspaceProfiles:
  default:
    devDependencies:
      "@yarnpkg/node": "builtin:^22.0.0"

# Compose a web profile from a shared tooling profile.
workspaceProfiles:
  tooling:
    devDependencies:
      typescript: "^5.0.0"
  web:
    extends:
      - "tooling"
    devDependencies:
      vite: "^6.0.0"

Version range required for the Yarn Switch binary.

When set, Yarn validates that the Yarn Switch binary version satisfies this semver range before executing any command.

# Require Yarn Switch 6 or newer.
switchVersionRequirement: "^6.0.0"

# Disable the Switch version requirement.
switchVersionRequirement: null

Default dependency catalog.

Maps package names to version ranges. This is an alias for catalogs.default, and entries can be referenced through the catalog: protocol.

# Define shared ranges for common dependencies.
catalog:
  react: "^19.0.0"
  typescript: "^5.0.0"

# Define scoped package ranges.
catalog:
  "@types/node": "^22.0.0"

Named dependency catalogs.

Named catalogs contain predefined version ranges for packages. Use catalog:name in dependencies to reference a named catalog.

# Define separate catalogs for app and tooling dependencies.
catalogs:
  react19:
    react: "^19.0.0"
    react-dom: "^19.0.0"
  tooling:
    typescript: "^5.0.0"

# Define an empty named catalog to fill in later.
catalogs:
  future: {}

Array of hostname glob patterns for which using the HTTP protocol is allowed.

# Allow HTTP for a single internal host.
unsafeHttpWhitelist:
  - "registry.internal.example"

# Allow HTTP for a whole internal domain.
unsafeHttpWhitelist:
  - "*.corp.example"

Path where virtual packages will be stored.

Due to a particularity in how Yarn installs packages which list peer dependencies, some packages will be mapped to multiple virtual directories that don't actually exist on the filesystem. This settings tells Yarn where to put them. Note that the folder name must be __virtual__.