/compare/bundler/bundle-install-vs-bundle-update
bundle install vs bundle update: differences and when to use each
- tool
- Bundler
- compares
- bundle install vs bundle update
bundle install installs exactly the versions in Gemfile.lock; when you add or change a gem in the Gemfile, it resolves only that gem (and what it needs) and keeps everything else locked. bundle update ignores the locked versions and upgrades gems to the newest versions the Gemfile allows, rewriting Gemfile.lock. Use bundle install day to day and in CI, and bundle update GEM when you deliberately upgrade a gem.
Side by side
| Criterion | bundle install | bundle update |
|---|---|---|
| Reads | Gemfile.lock, plus new or changed Gemfile entries | Gemfile (locked versions are ignored for the gems being updated) |
| Writes Gemfile.lock | Only for added or changed gems (or if it did not exist) | Yes |
| Upgrades existing gems | No | Yes |
| Scope | Whole bundle | Every gem, or only the named ones (bundle update rails) |
| Reproducible | Yes | No: depends on what was released |
| Typical use | After cloning or pulling, CI, deployments | Upgrading gems, security fixes |
Commands
bundle install # install what Gemfile.lock says
bundle update nokogiri # upgrade one gem (and dependencies only it uses)
bundle update nokogiri --conservative # do not upgrade its shared dependencies
bundle update --patch # only patch-level upgrades for all gems
bundle update --minor --strict # minor upgrades, never past the limit
bundle outdated # list gems with newer versionsIn CI and production, set bundle config set --local frozen true (or deployment mode) so bundle install fails instead of changing Gemfile.lock when it does not match the Gemfile.
Which one to use
- After cloning, pulling or switching branches:
bundle install. It installs whatGemfile.lockrecords, so you run the same gems as everyone else. - After adding a gem to the Gemfile:
bundle install. It resolves only the new gem and what it needs; existing gems keep their versions. - Upgrading on purpose:
bundle update GEM, one gem or a small group at a time, followed by the test suite. Use the level options to limit the jump. - Security advisories:
bundle update GEM --conservativemoves only the affected gem, which keeps the change small enough to review. - CI and production:
bundle installwith the frozen or deployment setting, neverbundle update.
Update options
| Option | Effect |
|---|---|
| bundle update GEM | Unlock GEM and the dependencies only it uses, then resolve again |
| --conservative | Also keep shared dependencies of GEM locked |
| --patch / --minor / --major | Prefer the newest patch, minor or major release when choosing versions |
| --strict | With a level option, never go beyond that level (otherwise Bundler may if resolution requires it) |
| bundle update --bundler | Update the Bundler version recorded under BUNDLED WITH |
| bundle lock --update GEM | Rewrite Gemfile.lock for GEM without installing anything |
How to read the result
After either command, git diff Gemfile.lock is the record of what changed. With bundle install after adding one gem, expect a few new lines in the specs list. With bundle update, check every version that moved: a minor bump of a framework gem can come with deprecations, and a major bump usually needs code changes. If a teammate pulls the new lock file and sees errors about missing gems, they only need bundle install; see Could not find gem in locally installed gems.
FAQ
Does bundle install ever upgrade gems?
Only the gems you added or whose requirement you changed in the Gemfile, plus dependencies that must move with them. Everything else stays at the version in Gemfile.lock.
How do I upgrade a single gem without touching the others?
Run bundle update GEM, and add --conservative so shared dependencies stay locked too. Review the Gemfile.lock diff before committing.
What happens if Gemfile.lock is missing?
bundle install resolves the whole Gemfile, installs the newest versions it allows and writes a new Gemfile.lock. Commit it so other machines install the same versions.