Should I upgrade to RubyGems / Bundler 4 Defaults and CLI now?
Plan the Ruby release pipeline upgrade before Bundler 4 default-path, flag, and UX changes break existing CI, Docker images, and developer workflows.
Blockers
- Bundler 2.7 includes `simulate_version 4` so teams can preview Bundler 4 behavior.
- Bundler 4 removes remembered `bundle install` flags such as `--path`, `--without`, `--deployment`, and `--frozen`.
- Bundler 4 changes the default install path to `.bundle` at the repository root.
- Bundler 4 includes lockfile checksums by default for new lockfiles.
- Ruby 4.0.0 shipped with RubyGems/Bundler 4.0.3.
Who this is for
- small-team
- monorepo
- enterprise
Candidates
Stage the migration on Bundler 2.7 using Bundler 4 simulation
As of 2026-04-03, Bundler 2.7 is the last release before Bundler 4 and includes `simulate_version 4` so teams can preview Bundler 4 behavior before the final cutover. Official docs say Bundler 4 changes the default install path to `.bundle` at the repository root, enables `clean` by default when `path` is not explicitly configured, enables `cache_all`, and includes lockfile checksums by default for new lockfiles. The upgrade guide also says Bundler 4 removes remembered `bundle install` flags such as `--path`, `--without`, `--deployment`, and `--frozen`, and enforces stricter source pinning in Gemfiles. This path is the lowest-risk way to surface CI, Docker, and developer-shell breakage while still running a pre-4 production toolchain.
When to choose
Use this when CI images, release scripts, or multiple apps still rely on implicit Bundler behavior and you need a rehearsal phase. It is the best choice when the decisive factor is finding hidden workflow dependencies before the Ruby or RubyGems upgrade lands everywhere.
Tradeoffs
Safer rollout and easier debugging, but you spend time maintaining transitional configuration and dual-behavior testing.
Cautions
Do not treat simulation as a no-op. You still need to replace bare `bundle` invocations with explicit commands, move persisted CLI flags into `bundle config` or environment variables, and audit Gemfiles for multiple global sources or global `git` and `path` declarations.
Cut over fully to RubyGems 4 and Bundler 4 with explicit config
As of 2026-04-03, the latest RubyGems and Bundler release visible in the official blog is 4.0.6, and Ruby 4.0.0 shipped with RubyGems/Bundler 4.0.3. Bundler 4 removes `bundle viz` and `bundle inject`, rejects `bundle install --binstubs`, and no longer supports remembered install flags, multiple global Gemfile sources, or global `git` and `path` sources. Official config docs also say Bundler 4 defaults `path` to `.bundle`, defaults `clean` to `true` when `path` is not explicitly configured, and defaults `default_cli_command` to `cli_help`; the upgrade guide additionally warns not to depend on bare `bundle` and to use `bundle install` explicitly. This option is the right choice when you want the ecosystem-aligned toolchain now and can update scripts, lockfiles, and Gemfiles in one coordinated change.
When to choose
Use this when you are already upgrading Ruby or base images and can make source, lockfile, and command-line fixes in the same release window. It is the best choice when the decisive factor is removing transitional complexity and standardizing all environments on current RubyGems/Bundler behavior.
Tradeoffs
Fastest long-term convergence, but highest immediate blast radius for CI, cached Docker layers, checked-in binstub workflows, and legacy Gemfile patterns.
Cautions
Existing lockfiles do not automatically get a `CHECKSUMS` section; official guidance is to run `bundle lock --add-checksums` if you want to upgrade them. If you relied on `bundle viz`, you now need the `bundler-graph` plugin, and if you relied on `gem install --default` or `gem query`, RubyGems 4 has already removed those behaviors.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to RubyGems / Bundler 4 Defaults and CLI now?"