The frozen setting disallows any automatic change to Gemfile.lock. Bundler commands are blocked unless the lock file can be installed exactly as written. The deployment setting is equivalent to frozen plus installing gems into vendor/bundle. Use them in CI and production, not on developer machines.
What the documentation says
The bundle config reference defines frozen as disallowing automatic changes to Gemfile.lock, and says it usually triggers when someone edits the Gemfile and forgets to update the lock file. Deployment is described as equivalent to setting frozen to true and path to vendor/bundle. The install page adds that deployment mode requires a Gemfile.lock and advises against enabling it on development machines, since it errors when the Gemfile changes.
| Setting | Effect | Where to use |
|---|---|---|
| frozen | Blocks lock file changes | CI, build, production |
| deployment | Frozen plus gems in vendor/bundle | Production deploys |
| path | Where gems are installed | Isolate per app |
Why this is a supply chain control
Without it, a pipeline can quietly re-resolve gems when the Gemfile and lock file drift apart. That is the same hole as running update at deploy time. With frozen on, the build fails loudly and a human has to fix the lock file in a reviewed change.
Steps to enable it
- Make sure Gemfile.lock is committed and current.
- Set the frozen option through config or the BUNDLE_FROZEN environment variable in CI.
- Run install. A mismatch now fails the job.
- Fix the mismatch locally with a deliberate update, then commit both files.
- Keep development machines out of frozen mode.
bundle config set frozen true
bundle install
What to expect when it fails
A failure usually means someone changed the Gemfile without running install locally, or a merge left the lock file inconsistent. Do not work around it by switching frozen off in CI. Fix the cause. Switching it off is the same as removing the guard.
Pair it with a lock file check
Frozen proves the lock file installs as written. It does not prove the lock file is free of known vulnerabilities. Add an advisory check on the locked versions, as in our guide to auditing a Gemfile.lock.
Try it yourself
Click through it at your own pace, or open it full screen. See how drift between declared and deployed dependencies gets surfaced.
Where Safeguard fits
Safeguard's SBOM and dependency scanning reads composer.lock and Gemfile.lock and flags known advisories. A free scan takes a few minutes.
Quick check
Is deployment mode the same as production environment?
No. It is a Bundler install setting, not the Rails environment. It controls the lock file and the gem path.
Can I use frozen with a vendored cache?
Yes. Frozen concerns the lock file, while vendor/cache concerns where gem files come from.
Sources
Last reviewed: 19 October 2026.
