deno install --frozen: fail when deno.lock is out of date

deno install --frozen (alias --frozen-lockfile) installs dependencies only if deno.lock already matches deno.json. When a dependency was added or changed without updating the lockfile, Deno stops with The lockfile is out of date instead of rewriting deno.lock. Use it in CI so every build uses exactly the versions that were committed; locally, run deno install without the flag to update the lockfile and commit it.

Out-of-date lockfile

A first deno install writes deno.lock; then a second dependency is added to deno.json by hand:

cat > deno.json <<'EOF'
{ "imports": { "is-number": "npm:is-number@7.0.0" } }
EOF
npx --yes deno@2 install 2>/dev/null
ls deno.lock
cat > deno.json <<'EOF'
{ "imports": { "is-number": "npm:is-number@7.0.0", "is-odd": "npm:is-odd@3.0.1" } }
EOF
echo "--- deno install --frozen"
npx --yes deno@2 install --frozen 2>&1 | grep -v "^ *$"; echo "exit: ${PIPESTATUS[0]}"
echo "--- deno install (updates the lockfile)"
npx --yes deno@2 install 2>/dev/null; echo "exit: $?"
npx --yes deno@2 install --frozen 2>/dev/null; echo "frozen again, exit: $?"

deno.lock
--- deno install --frozen
Download https://registry.npmjs.org/is-odd
error: The lockfile is out of date. Run `deno install --frozen=false`, or rerun with `--frozen=false` to update it.
changes:
 4 | -    "npm:is-number@7.0.0": "7.0.0"
 4 | +    "npm:is-number@7.0.0": "7.0.0",
 5 | +    "npm:is-odd@3.0.1": "3.0.1"
   | ...
 8 | +    "is-number@6.0.0": {
 9 | +      "integrity": "sha512-Wu1VHeILBK8KAWJUAiSZQX94GmOE45Rg6/538fKwiloUu21KncEkYGPqob2oSZ5mUT73vLGrHQjKw3KMPwfDzg=="
10 | +    },
   | ...
13 | +    },
14 | +    "is-odd@3.0.1": {
15 | +      "integrity": "sha512-CQpnWPrDwmP1+SMHXZhtLtJv90yiyVfluGsX5iNCVkrhQtU3TQHsUWPG9wkdk9Lgd5yNpAg9jQEo90CBaXgWMA==",
16 | +      "dependencies": [
17 | +        "is-number@6.0.0"
18 | +      ]
   | ...
13 | -      "npm:is-number@7.0.0"
23 | +      "npm:is-number@7.0.0",
24 | +      "npm:is-odd@3.0.1"
exit: 1
--- deno install (updates the lockfile)
exit: 0
frozen again, exit: 0

The error lists what changed and how to update the lockfile. After a normal deno install the lockfile matches again and --frozen succeeds.

Where the flag applies

CI setup

deno install --frozen        # restore dependencies exactly as locked
deno check main.ts
deno test --frozen

The lockfile also stores integrity hashes. Deno checks them on every download with or without --frozen; a mismatch means the package content changed and is a separate, more serious error.

Pitfalls

• deno add updates both deno.json and deno.lock; editing deno.json by hand is the usual way to end up with a stale lockfile. See deno add.
• An import that is not listed in deno.json at all produces a different error: Import is not a dependency.
• Other package managers have the same idea under other names: npm ci, yarn install --immutable, pnpm install --frozen-lockfile and bun install --frozen-lockfile.

FAQ