Ever had a build fail for no obvious reason?
No code changes.
No dependency updates.
Nothing that should’ve broken anything.
Yet CI is red. A teammate can’t reproduce the issue. Production behaves differently from yesterday.
That’s not bad luck.
That’s your lockfile being ignored.
And the fix is simpler than you think.
The Lockfile Is the Real Source of Truth
In every Yarn project, two files work together:
-
package.jsondefines what’s allowed -
yarn.lockdefines what actually gets installed
If Yarn is allowed to rewrite the lockfile during installation, you’re no longer guaranteed the same dependencies every time.
You’re hoping you are.
Hope is not a build strategy.
What “Frozen” (or Immutable) Installs Actually Mean
A frozen or immutable install tells Yarn:
- Install exactly what’s in
yarn.lock. - If anything doesn’t match, fail immediately.
No silent upgrades.
No registry surprises.
No mysterious diffs showing up in PRs.
It turns your lockfile into a contract, not a suggestion.
Why This One Setting Changes Everything
Without frozen installs:
- Builds change over time
- CI depends on timing and registry state
- Bugs appear without code changes
- Rollbacks don’t restore previous behavior
With frozen installs:
- Identical installs across machines
- Early, predictable CI failures
- Less time debugging environments
- More confidence shipping changes
How to Do This with Yarn (By Version)
Yarn v1 (Classic)
Yarn v1 does not freeze installs by default.
You must opt in:
yarn install --frozen-lockfile
This prevents Yarn from modifying yarn.lock.
Always use this in CI.
Yarn Berry (v2 / v3)
Yarn Berry improves things significantly.
CI environments
When CI=true (GitHub Actions, GitLab CI, CircleCI):
yarn install
That’s it.
Yarn automatically enforces immutable installs.
If yarn.lock doesn’t match package.json, the build fails.
No extra flags required.
Want the same strictness locally?
yarn install --immutable
Now local installs behave exactly like CI.
When Lockfiles Should Change
Lockfiles should change only when you:
- Add a dependency
- Upgrade a package
- Intentionally modify versions They should never change just because someone ran yarn install.
If they do, your process — not your code — is broken.
The Hidden Benefit: Confidence
When installs are immutable:
- A green build actually means something
- A rollback restores behavior, not surprises
- Bugs come from code changes, not environment drift
That confidence compounds across teams and deployments.
Final Thought
Most “random” bugs aren’t random at all.
They’re caused by installs that were too flexible and lockfiles that weren’t treated seriously.
Yarn gives you the tools to lock things down — especially with Berry making immutability the default in CI.
So let your lockfile do its job.
Freeze it.
Trust it.
Ship with confidence. 🚀
Top comments (0)