[Bug?]: `yarn install --immutable` should be default behavior

[k0pernikus]

Self-service

• I'd be willing to implement a fix

Describe the bug

This is basically a repeat of my request that yarn install --frozen-lockfile should be the default, now though with the --immutable flag instead.

Use case:

yarn init
yarn add moment
npm install --save lodash
yarn install

Now, running yarn install would mutate the lock as the package.json and yarn.lock and are out of sync.

yarn install --immutable would provide an error.

(The usage of npm is a mistake in this workflow. Yet yarn should not resolve the package.json and mutate the lockfile by itself. yarn should error on the side of caution in order to ensure its claim to offer:

Safe, stable, reproducible projects

I still think that mutating the lockfile is something that yarn should almost never do, unless it is about adding or removing a dependency.

---

Though I also want to point out that berry does a lot of things better than the old yarn.

1.) CI env variable allows immutable implicitly. That is great!

I figured I could get my wanted behavior via:

CI=true yarn install

to force a default of --immutable without setting it.

2.) immutable can be set in yarn.rc AND overwritten on the fly in order to sync the package

I added:

enableImmutableInstalls: true

this makes all installs use immutable. If I want to sync the packages, I can use:

yarn install --no-immutable

to force the sync.

This means that having this setting in the each repo's .yarnrc.yml

(This means that yarnpkg/yarn#4570 was solved for berry.)

Though I was a bit surprised that I could use --no-immutable, as this is not part of the help, yet one can find it e.g. referenced here.

(I created a follow up to improve the docs / man pages: #7023 )

yarn install -h | grep no-

so having a more clear documentation for the --no- prefix would be awesome.

To reproduce

yarn init
yarn add moment
npm install --save lodash
yarn install

yarn install should fail but succeeds:

yarn install
➤ YN0087: Migrated your project to the latest Yarn version 🚀

➤ YN0000: · Yarn 4.12.0
➤ YN0000: ┌ Resolution step
➤ YN0085: │ + lodash@npm:4.17.21, moment@npm:2.30.1
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed
➤ YN0000: · Done in 0s 63ms

The behavior of yarn install --immutable is the expected and desired one as a default:

~  yarn install --immutable
➤ YN0000: · Yarn 4.12.0
➤ YN0000: ┌ Resolution step
➤ YN0085: │ + lodash@npm:4.17.21, moment@npm:2.30.1
➤ YN0000: └ Completed

➤ YN0000: ┌ Post-resolution validation
➤ YN0000: │ @@ -1,13 +1,27 @@
➤ YN0028: │ -# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
➤ YN0028: │ -# yarn lockfile v1
➤ YN0028: │ +# This file is generated by running "yarn install" inside your project.
➤ YN0028: │ +# Manual changes might be lost - proceed with caution!
➤ YN0000: │
➤ YN0028: │ +__metadata:
➤ YN0028: │ +  version: 8
➤ YN0028: │ +  cacheKey: 10c0
➤ YN0000: │
➤ YN0028: │ -lodash@^4.17.21:
➤ YN0028: │ -  version "4.17.21"
➤ YN0028: │ -  resolved "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"
➤ YN0028: │ -  integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
➤ YN0028: │ +"lodash@npm:^4.17.21":
➤ YN0028: │ +  version: 4.17.21
➤ YN0028: │ +  resolution: "lodash@npm:4.17.21"
➤ YN0028: │ +  languageName: node
➤ YN0028: │ +  linkType: hard
➤ YN0000: │
➤ YN0028: │ -moment@^2.30.1:
➤ YN0028: │ -  version "2.30.1"
➤ YN0028: │ -  resolved "https://registry.npmjs.org/moment/-/moment-2.30.1.tgz"
➤ YN0028: │ -  integrity sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==
➤ YN0028: │ +"moment@npm:^2.30.1":
➤ YN0028: │ +  version: 2.30.1
➤ YN0028: │ +  resolution: "moment@npm:2.30.1"
➤ YN0028: │ +  languageName: node
➤ YN0028: │ +  linkType: hard
➤ YN0028: │ +
➤ YN0028: │ +"new_yarn@workspace:.":
➤ YN0028: │ +  version: 0.0.0-use.local
➤ YN0028: │ +  resolution: "new_yarn@workspace:."
➤ YN0028: │ +  dependencies:
➤ YN0028: │ +    lodash: "npm:^4.17.21"
➤ YN0028: │ +    moment: "npm:^2.30.1"
➤ YN0028: │ +  languageName: unknown
➤ YN0028: │ +  linkType: soft
➤ YN0000: │
➤ YN0028: │ The lockfile would have been modified by this install, which is explicitly forbidden.
➤ YN0000: └ Completed
➤ YN0000: · Failed with errors in 0s 32ms

Environment

yarn dlx -q envinfo --preset jest

  System:
    OS: Linux 5.15 Ubuntu 25.04 25.04 (Plucky Puffin)
    CPU: (32) x64 AMD Ryzen 9 5950X 16-Core Processor
  Binaries:
    Node: 24.12.0 - /tmp/xfs-cf945491/node
    Yarn: 4.12.0 - /tmp/xfs-cf945491/yarn
    npm: 11.6.2 - /home/philipp/.nvm/versions/node/v24.12.0/bin/npm

Additional context

No response

[arcanis]

As you mention the immutable flag is automatically turned on on CI. In local development I don't see why it would be automatically set, considering that if you pull you're already sure the lockfile won't change spuriously (because your colleagues' PRs were validated by said CI already).

[k0pernikus]

As you mention the immutable flag is automatically turned on on CI. In local development I don't see why it would be automatically set, considering that if you pull you're already sure the lockfile won't change spuriously (because your colleagues' PRs were validated by said CI already).

A CI may exist, yet a project might not have one. One shouldn't work with this assumption that the detection of the unsynced state happens there. Nor should this be the expected discovery. Having a CI fail while no problem occurred on the local development machine is counterintuitive behavior. It wastes computing time of the CI and developer time to fix this.

I, as a developer, would expect an error as early in the workflow as possible, and that's on my local machine just by running yarn install whenever the package.json and yarn.lock are out of sync.

(That means commands like yarn add as well, as they shouldn't just lock in dependencies on their own when unsynced. Though they too might allow that via a flag.)

Why default?

I will use the .yarnrc with enableImmutableInstalls: true for all my projects. That alone indicates: should be default behavior.

Though since --no-immutable isn't in the docs, it would be on me to inform any other developer on each project that they can use that to sync the yarn.lock. (Though that is only likely for developers having muscle memory of using npm.)

As I have said, I can work with the current state of berry much better than with the old yarn. Though yarn's odd behavior to sync and optimize the lock file has been a source of many misunderstandings and unexpected problems in the past.

Since yarn is used to ensure reproducible dependencies, it's still odd that I have to get out of my way to ensure that my packages really are immutable during a basic yarn install.