bundle install: Usage, Options & Common CI Errors

bundle install installs the exact gems pinned in Gemfile.lock for a Ruby project.

bundle install is how Ruby projects install dependencies reproducibly. In CI the central concern is frozen/deployment mode, which guarantees the lockfile is respected and not silently rewritten.

What it does

bundle install reads the Gemfile, resolves dependencies against Gemfile.lock, and installs the exact versions. In CI you run it in frozen/deployment mode so a Gemfile change without a matching lockfile update fails the build instead of quietly updating the lock. Caching the vendor/bundle path speeds repeat runs.

Common usage

bundle install --jobs 4 --retry 3
bundle config set --local deployment true
bundle config set --local path vendor/bundle
bundle install                                   # frozen, into vendor/bundle
bundle install --frozen                           # legacy flag form

Common errors in CI

"The dependencies in your gemfile changed ... but the lockfile can't be updated because frozen mode is set" (or "Your bundle is locked to ... but that version could not be found") means you edited the Gemfile without running bundle install locally and committing Gemfile.lock - regenerate and commit the lock. "Could not find X in any of the sources" is a missing/yanked gem or wrong source. Native-extension builds fail without build tools. Set --jobs and --retry to speed up and harden flaky installs.

Options

Related guides