yarn install --frozen-lockfile (Yarn 1) and --immutable (Yarn 2+)

yarn install --frozen-lockfile installs dependencies from yarn.lock and fails if the lockfile would have to change, instead of silently updating it. Use it in CI so builds use exactly the versions you committed. It is a Yarn 1 (Classic) flag; Yarn 2 and later replace it with --immutable, which is turned on automatically when Yarn detects a CI environment.

The error when yarn.lock is out of date

A dependency is in package.json but not in yarn.lock (here the lockfile is empty):

cat > package.json <<'EOF'
{ "name": "app", "version": "1.0.0", "license": "MIT", "dependencies": { "is-number": "7.0.0" } }
EOF
touch yarn.lock
npx --yes yarn@1 install --frozen-lockfile --non-interactive

yarn install v1.22.22
[1/4] Resolving packages...
error Your lockfile needs to be updated, but yarn was run with `--frozen-lockfile`.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

The same situation with Yarn 4 and --immutable (Yarn 4 runs here from its npm distribution, @yarnpkg/cli-dist):

cat > package.json <<'EOF'
{ "name": "app", "version": "1.0.0", "license": "MIT", "dependencies": { "is-number": "7.0.0" } }
EOF
touch yarn.lock
npx --yes @yarnpkg/cli-dist@4 install --immutable > install.log 2>&1
status=$?
grep -o 'YN0028: The lockfile.*' install.log
exit $status

(no output)

Fix

Update the lockfile on a development machine and commit it:

yarn install            # rewrites yarn.lock
git add yarn.lock package.json
git commit -m "Update yarn.lock"

Then CI can keep --frozen-lockfile.

Yarn 1 vs Yarn 2+