RubyGems and Bundler

Four things are easy to confuse. The table separates them; later sections go through each one.

The versions of RubyGems and Bundler follow the Ruby release. The table lists what was installed with the Ruby patch releases used to check this page.

Both tools can be updated independently of Ruby: gem update --system installs the newest RubyGems, and gem install bundler installs a newer Bundler next to the default one, which cannot be uninstalled. A project selects its Bundler through the BUNDLED WITH section of its lockfile (see Gemfile.lock).

A gem is a packaged Ruby library or program with a name, a version and a platform, plus the metadata that lets tools install it and its dependencies. The name and version identify it (rake 13.3.1); the platform says where it runs: ruby means the gem is delivered as Ruby source (or as C source that is compiled at install time) and installs everywhere, while a concrete platform such as arm64-darwin or x86_64-linux marks a precompiled binary. The full name of a file is name-version.gem or name-version-platform.gem.

Inside a .gem file (a plain tar archive) are three entries, which the example below lists after building the running shelf gem with gem build: metadata.gz (the gemspec, serialized as YAML), data.tar.gz (the files of the gem) and checksums.yaml.gz (SHA-256 and SHA-512 digests of the other two).

The date 1980-01-02 is not a mistake: gem build uses a fixed timestamp so that building the same input twice produces byte-identical files (the SOURCE_DATE_EPOCH environment variable overrides it). The gem rebuild command uses this property to check that a published gem can be reproduced from its source. gem unpack extracts the data.tar.gz part, which is how you inspect what a gem really contains before using it.

Source: RubyGems Guides: What is a gem?

gem is the command-line front end of RubyGems. A short tour of the commands that matter day to day follows; gem help commands lists all of them and gem help COMMAND documents one. Commands may be abbreviated when unambiguous (gem i rake is gem install rake).

RubyGems 4 removed gem query (use gem search or gem list) and the gem install --default option, and moved gem generate_index, gem mirror and gem server out of the core into separate gems (gem help commands still lists them with a "requires rubygems-…​" note).

A gem version is a string of numbers, dots and letters. RubyGems attaches no meaning to its parts; what a bump signifies is up to each gem. The convention that much of the ecosystem assumes is semantic versioning (MAJOR.MINOR.PATCH: patch for fixes, minor for compatible additions, major for breaking changes), but it is a convention, not a rule that RubyGems enforces, and Ruby itself does not follow it (it releases a new minor version every 25 December and allows incompatible changes in it). Gem::Version compares versions the way tools need:

A requirement (Gem::Requirement) is a list of operator and version pairs, and a dependency (Gem::Dependency) couples a gem name with a requirement and a type (:runtime or :development). These are the operators, in Gemfile and gemspec syntax:

A list of requirements means "all of them": gem "rack", ">= 2.2", "< 4.0", "!= 3.0.1". Pick the level of change you are prepared to absorb automatically: ~> 2.2 accepts 2.9.9, while ~> 2.2.0 stays inside 2.2.x.

Output of ruby -w versions.rb (the # => comments are those values):

Notice the prerelease rule: Gem::Requirement#satisfied_by? only compares numbers, so >= 1.0 is satisfied by 2.0.0.rc1, but Gem::Dependency#match?, which is what installers and resolvers use, skips prereleases unless the requirement itself names one. That is why gem install shelf installs the newest stable release, gem install shelf --pre allows prereleases, and Bundler considers a prerelease only for a requirement such as gem "shelf", ">= 1.0.0.rc1".

Source: Ruby 4.0 documentation: Gem::Version, Gem::Requirement and Gem::Dependency

Ruby loads RubyGems at start-up, and RubyGems replaces Kernel#require. When the file to require is not already on $LOAD_PATH, RubyGems searches the installed gems for one that contains it, picks the newest version, activates it (adds its lib directory and those of its dependencies to $LOAD_PATH) and then performs the ordinary require. Activation is per process and exclusive: several versions of a gem can be installed, but only one can be active, and activation also sets Gem.loaded_specs. To load something other than the newest version, call Kernel#gem before the require.

Output of ruby -w activation.rb (the gem count depends on the machine):

Gem::LoadError ("can’t activate …​, already activated …​") is the error behind version conflicts in plain scripts: two gems, directly or through their dependencies, demanded different versions of a third one. Gem::MissingSpecError (a subclass) means no installed version satisfies the request, and a plain LoadError ("cannot load such file") means no installed gem contains the file at all. gem which NAME prints the path a require would load. Compiled extensions are found through the gem’s extensions directory (the second $LOAD_PATH entry of a gem with an extension). Default gems live in specifications/default/ and load without being installed; a newer version installed from RubyGems.org takes precedence over the shipped one.

Source: Ruby 4.0 documentation: Kernel#gem and Gem::LoadError

Under Bundler the picture changes: require "bundler/setup" (done for you by bundle exec) rebuilds the load path from the lockfile so that only the locked versions of the gems in the bundle are visible. The rest of the gem home stays installed but cannot be required (see Running code in the bundle).

Much of Ruby’s standard library is packaged as gems that can be updated independently of Ruby. They fall into two classes that behave differently under Bundler, and mixing them up is the most common reason for a LoadError after upgrading Ruby.

A default gem can always be required without a Gemfile entry; it is what Ruby ships unless the Gemfile (or gem install) provides a newer version. A bundled gem is installed alongside Ruby so that scripts can use it, but Bundler’s job is to make the Gemfile the single source of truth for what a project can load, so it hides everything that is not listed, bundled gems included.

Output of ruby -w kinds.rb:

(regular gem here means "not a default gem": logger and the others are bundled gems; RubyGems itself does not record the difference, Gem::Specification#default_gem? is the only flag.) Set has been a core class since 4.0 and Pathname too, which is why neither needs a require or a gem any more; SortedSet was removed and lives in the community sorted_set gem.

Source: Ruby 4.0 documentation: Gem::BasicSpecification#default_gem?

gem install installs what you ask for and activates the newest installed version when you require. That is fine for a script and a poor foundation for an application: two machines that install the same gem names at different times get different versions, two applications on one machine want different versions of the same gem, and nothing records which combination last worked. Bundler solves this with a declaration and a snapshot. The Gemfile declares what the project depends on (names, constraints, groups, sources); Bundler resolves one consistent set of versions that satisfies all of those constraints and all of the dependencies' own constraints, writes the exact result to Gemfile.lock, installs it, and from then on makes sure that running the project loads exactly that set. Every machine and every deploy that starts from the same lockfile runs the same code.

Source: RubyGems Guides: How to manage dependencies with Bundler and How to manage application dependencies with Bundler

The everyday loop has four steps: edit the Gemfile (or let bundle add do it), run bundle install (which re-resolves only what changed), commit Gemfile and Gemfile.lock, and run the project with bundle exec. The rest of this section of the page explains each piece.

A Gemfile is Ruby code evaluated in a context that provides a small DSL. It lives in the project root; Bundler finds it by searching upward from the current directory (BUNDLE_GEMFILE overrides this and also sets the project root). bundle init writes a starter file. This is the Gemfile of the running shelf gem, the layout that bundle gem generates:

Source: RubyGems Guides: Gemfile and gemspec

source declares where gems come from, gemspec pulls the gem’s own gemspec in (its runtime dependencies in the default group, its development dependencies in the development group, and the gem itself as a path: dependency so tests can require it), and each gem line adds a dependency. As a rule the gemspec carries the runtime dependencies of a gem and the Gemfile carries its development tools (minitest, rake, rubocop), while an application declares everything in the Gemfile.

Groups let one Gemfile describe several environments. A gem outside any group is in :default. Groups control three things: what bundle install installs, what Bundler.setup puts on the load path, and what Bundler.require requires.

Source: RubyGems Guides: How to manage groups of gems

With the Gemfile above, a default bundle install --local installs the default and test groups (4 gems: logger, minitest, rake and prism, which minitest depends on) and leaves the optional development group (RuboCop and its 14 dependencies) alone. The real outputs:

Source: RubyGems Guides: How to manage groups of gems

(After bundle config set --local with development the same bundle install --local reports 18 gems now installed.) The script below selects groups in code; run with bundle exec it shows Bundler.require skipping a group that was not set up:

Source: RubyGems Guides: How to manage groups of gems

git: installs a gem from a repository, which is how you use an unreleased fix or a private gem that is not on any server. Bundler clones the repository, finds the gemspec(s) (a repository with several gemspecs is a multi-gem source; glob: locates a gemspec in a subdirectory), builds the gem and installs it. path: uses a directory on disk, read again on every run, which is how a gem is developed alongside the application that uses it; unlike git:, Bundler does not compile C extensions for path gems. Both require either a gemspec in the directory or an explicit version in the gem line. Specify a branch:, tag: or ref: (at most one; without any, Bundler follows the default branch of the repository), use https or ssh URLs (the unauthenticated git:// and http:// protocols let a man-in-the-middle substitute code), and prefer a tag or a commit to a moving branch. The shorthands github: "owner/repo" (also github: "owner" when both names are equal, and a pull-request URL), gist: and bitbucket: expand to https URLs. Gems installed from git do not appear in gem list; they are available after Bundler.setup. bundle config set local.GEM /path/to/clone overrides a git source with a local checkout for development (it requires a branch: in the Gemfile and checks that the branch matches).

A complete local experiment, with a throwaway git repository created next to the application (paths are shortened) so that nothing is downloaded. The Gemfile and the lockfile that Bundler wrote:

Source: RubyGems Guides: Gemfile path sources and How to install gems from git repositories

Observe the GIT section (the revision: is pinned, so a later install uses exactly that commit even if the tag or branch moves), the PATH section (only the location is recorded), the ! marks in DEPENDENCIES (a gem pinned to a non-default source) and the empty CHECKSUMS entries: gems from git and path sources have no packaged .gem file to digest. The clone and the checkout live in the gem home under cache/bundler/git/ and bundler/gems/.

Source: RubyGems Guides: How to install gems from git repositories

Gemfile.lock is Bundler’s output: the exact version of every gem, direct or transitive, plus the sources, platforms, Ruby version and Bundler version. You never edit it by hand. The first bundle install resolves and writes it; later installs reuse it, which is why they are fast and reproducible. This is the real lockfile of the shelf gem (SHA-256 digests shortened):

Source: RubyGems Guides: How Gemfile.lock works

Section by section:

Commit the lockfile of an application. It is how a teammate or a deploy reproduces your exact versions; an uncommitted lockfile silently turns every install into a fresh resolution. For a gem, the lockfile is not part of the package: when an application depends on your gem, Bundler resolves your gemspec’s dependencies together with everything else and ignores any Gemfile.lock the gem might ship. Whether to commit the lockfile in a gem’s own repository is a separate trade-off (committing it gives contributors a working environment; leaving it out lets CI notice a new dependency release that breaks the gem), and the Bundler documentation now recommends committing it.

Two housekeeping rules. Normalize platforms before committing: bundle lock --normalize-platforms rewrites arm64-darwin-23 to the version-less arm64-darwin (so lockfiles from different macOS releases agree) and adds every platform the locked gems are precompiled for. And never resolve a merge conflict in Gemfile.lock by hand: restore one side (git checkout HEAD — Gemfile.lock), merge the Gemfile, then run bundle install and Bundler re-locks only what the merged Gemfile changed.

Platform edits are local operations, so they can be tried offline:

(The two blocks are the PLATFORMS sections after each command.) Add the platform of the deploy target (x86_64-linux, aarch64-linux, x86_64-linux-musl) when you develop on macOS and deploy on Linux, otherwise a frozen install on the server stops with "Your bundle only supports platforms …​ but your local platform is …​".

Source: RubyGems Guides: How Gemfile.lock works

Before installing anything, Bundler has to choose one version of every gem. Taking the newest version of everything fails as soon as two gems need different versions of a third: suppose payments (newest) wants money >= 7.0 and every reporting release wants money ~> 6.1; an older payments that accepts money 6.x is the answer, and finding it means searching combinations, not looking up gems one by one. Bundler solves this with PubGrub, a version-solving algorithm from Dart’s package manager (it replaced Molinillo in Bundler 2.4, which shipped with Ruby 3.2): it explores candidate versions, learns from each dead end which combinations can never work and skips them, and when no solution exists it explains why. RubyGems' own resolver, used by gem install, moves from Molinillo to PubGrub in the RubyGems 4.1 beta.

Resolution takes into account the version constraints of the Gemfile and of every gemspec, the platforms, the required_ruby_version of each candidate, prerelease rules (never chosen unless named) and, since Bundler 4.0.13, the cooldown. It does not happen on every install: a lockfile that matches the Gemfile is reused as is.

When resolution fails the message walks the chain of requirements. This is real output, from two path gems in a scratch Gemfile, one depending on rbs ~> 3.10 and the other on rbs ~> 4.2 (both versions of rbs are installed locally, so the failure is a true conflict):

Source: RubyGems Guides: Troubleshooting common issues

Read it from the bottom: the Gemfile needs a and b, and the two requirements on rbs cannot both hold. The fix is a different version of a or b that agrees, a looser constraint, or dropping one of them. A different message appears when a gem or version is simply not available in the configured sources, for example with --local and an uninstalled gem:

Source: RubyGems Guides: Troubleshooting common issues

bundle help lists the commands (the manual page opens in a pager) and bundle help COMMAND documents one. Running bundle with no arguments still ran bundle install in Bundler 4.0.20 (printing a notice that this will change to showing the help and that bundle config set default_cli_command install --global keeps it); always write bundle install explicitly in scripts and documentation.

These are the real outputs of the read-only commands in the shelf project:

(The test run’s seed and timing differ on every run.) bundle outdated without --local asks the source for newer versions, so it needs the network; it annotates versions that are newer but still inside the cooldown window, for example 1.1256.0 (cooldown 3d).

bundle add is not run here because it downloads. It edits the Gemfile and runs bundle install; Bundler 4 removed the old bundle inject command (it printed [REMOVED] The inject command has been replaced by the add command), whose interface bundle add accepts unchanged.

Source: bundle install, bundle add, bundle outdated and bundle lock

Installing a bundle does not by itself change how Ruby finds gems; something must restrict the load path to the locked set. There are three ways, all of which end in the same Bundler.setup call.

Source: RubyGems Guides: How to use Bundler with Ruby and bundle binstubs

A script with a few dependencies should not need a project directory. require "bundler/inline" defines gemfile, which takes a block that is evaluated as a Gemfile. Gems that are already installed are activated; missing ones are installed first; then the gems are required (unless require: false) and the load path is restricted to them, exactly as bundle exec would. The script is self-contained and its dependencies are declared in the file.

Source: RubyGems Guides: How to use Bundler in a single-file Ruby script

Output of ruby -w inline_report.rb (all gems were installed, so nothing was downloaded; with a missing gem the first run installs it and prints Bundler’s progress only when gemfile(true) asks for it):

Points to know:

Source: RubyGems Guides: How to use Bundler in a single-file Ruby script and Ruby 4.0 documentation: Bundler

Some gems contain C (or Rust, or Go) extensions that must be compiled for the Ruby and the operating system that load them. RubyGems models this with platforms. The platform of a gem file is ruby (source, compiled at install time or pure Ruby) or a concrete platform such as arm64-darwin, x86_64-linux-gnu, x86_64-linux-musl or x64-mingw-ucrt; java marks JRuby builds. A gem that ships precompiled binaries publishes the same version once per platform, and gem install and bundle install choose the variant that matches your machine, falling back to the ruby gem (and a compiler) when no binary matches. A -gnu Linux binary is never selected on a musl system such as Alpine, and a bare x86_64-linux binary matches both.

Output of ruby -w platform.rb on an Apple-silicon Mac:

Gem::Platform and Gem::NameTuple support pattern matching since RubyGems 4.0 (Ruby 4.0); on Ruby 3.4 the case above falls to the else branch and the NameTuple match raises NoMatchingPatternError, because the classes do not define deconstruct_keys. See Pattern Matching for the syntax.

Platforms in the lockfile. PLATFORMS records the platforms the resolution covers. A fresh Bundler 4 lockfile for an application that depends on a gem with precompiled variants covers all of them. Installing on a platform that is not covered normally just works (Bundler adds the local platform and updates the lockfile), but on a frozen CI or production install the same situation fails with "Your bundle only supports platforms […​] but your local platform is x86_64-linux", and the fix is the one in the message: bundle lock --add-platform x86_64-linux, or bundle lock --normalize-platforms to add every platform the locked gems are precompiled for. The Gemfile platforms :jruby do ... end block is a different concept: it groups dependencies by Ruby implementation (:ruby, :mri, :jruby, :truffleruby, :windows, with optional versions such as :mri_34), not lockfile platforms.

Forcing the source build. When a precompiled binary misbehaves, or its required_ruby_version excludes a Ruby that the source gem supports, ignore your platform: bundle config set --local force_ruby_platform true, a single gem with gem "ffi", force_ruby_platform: true, or gem install nokogiri --platform ruby.

Building extensions. A source gem with an extension needs a compiler and the headers of the library it wraps (for example libpq for pg). RubyGems 4 runs make in parallel by default (MAKEFLAGS=-j, with a job count that follows the number of processors; set MAKEFLAGS or use gem install -j N to change it) and passes BUNDLE_JOBS down to it, so BUNDLE_JOBS=2 limits both the parallel downloads and the compile jobs in a small CI container. Build flags for one gem are stored with bundle config set --global build.pg --with-pg-config=/path/to/pg_config. Writing extensions is covered in C Extensions, FFI and WebAssembly. RubyGems 4.1 (in beta) adds content-addressable gem files that carry one build per platform and Ruby ABI.

Source: RubyGems Guides: Platforms and native gems and Ruby 4.0 documentation: Gem::Platform

Bundler is configured with bundle config, not with .gemrc. The rules:

The commonly used settings:

Credentials for private sources are configuration, never Gemfile text: bundle config set --global gems.example.com USER:TOKEN, or the environment variable BUNDLE_GEMS__EXAMPLE__COM (a dot becomes two underscores and a hyphen three). Credentials set this way are redacted in bundle config output. For a private git repository over https, BUNDLE_GITHUB__COM holds a token. Use placeholders in documentation and CI variables or secret stores for the real values; do not commit them to .bundle/config (which belongs in .gitignore when it holds anything but harmless settings).

Mirrors are configured with bundle config set --global mirror.https://rubygems.org https://mirror.example.com, with an optional mirror.URL.fallback_timeout after which the original server is tried.

Source: RubyGems Guides: bundle config

An application’s dependencies should reach production exactly as they were tested. The recipe has four parts: commit the lockfile, install with the lockfile frozen so that nothing is re-resolved, install into a project-local directory, and leave out groups that production does not need.

Source: RubyGems Guides: How to deploy bundled applications

The equivalent with environment variables, which suits a Dockerfile or a CI job: BUNDLE_DEPLOYMENT=true, BUNDLE_WITHOUT="development:test" (or BUNDLE_FROZEN=true and BUNDLE_PATH=vendor/bundle). If the Gemfile and the lockfile differ in frozen mode, the install stops instead of silently changing versions. This is the real message when gem "rainbow" was added to the Gemfile of the shelf project (whose lockfile has checksums) and the lockfile was not updated:

Source: RubyGems Guides: How to use Bundler in CI

Do not enable frozen or deployment mode on a development machine: it makes every Gemfile edit fail.

GitHub Actions. The ruby/setup-ruby action installs Ruby and, with bundler-cache: true, runs bundle install and caches the gems, keyed on the lockfile; with a lockfile present it installs in deployment mode, so an out-of-date lockfile fails the job. The Ruby version can come from .ruby-version, .tool-versions or mise.toml, and a matrix tests several Rubies:

To test several Gemfiles, set BUNDLE_GEMFILE in the job’s env. On GitLab CI, install into the project (bundle config set --local path vendor/ruby) and cache that directory keyed on Gemfile.lock. Configure Bundler through BUNDLE_* variables rather than bundle config commands in each job, and keep the Ruby versions of the matrix in line with the required_ruby_version of a gem (Ruby 3.2 and older are end of life; see Versions, Releases and Compatibility).

Source: RubyGems Guides: How to use Bundler in CI and How to deploy bundled applications

Installing a gem runs someone else’s code with your privileges, and a Gemfile decides which code that is. RubyGems and Bundler provide layers of defense; none replaces review, a lockfile and a test suite.

Lockfile and checksums. Gemfile.lock pins every version, and since Bundler 4 new lockfiles carry a CHECKSUMS section: Bundler verifies the SHA-256 of each downloaded .gem against it, so a gem substituted after the lockfile was written (a compromised mirror, a re-published tag) fails to install. For an existing lockfile, bundle lock --add-checksums adds the section; disable_checksum_validation exists for emergencies and should stay unset. Review lockfile changes in pull requests like code changes, and never resolve a lockfile merge conflict by hand.

Cooldown. Most malicious releases are found and yanked within days. Bundler 4.0.13 added an opt-in cooldown that keeps resolution away from versions younger than N days:

Source: RubyGems Guides: How to delay new gem versions with cooldown

The effective value comes from three layers, highest first: the --cooldown flag (install, update, add, outdated), the cooldown setting, and the per-source cooldown: keyword in the Gemfile; 0 disables it for the run. A value must be a non-negative integer. It takes effect only during resolution (an existing lockfile is honored as is, so enabling it never disturbs versions already locked), and it depends on the server publishing a per-version creation time in the v2 compact index: versions of servers that do not are treated as outside the window and stay resolvable. A cooldown also delays security fixes, hence the escape hatch. If a dependency bot proposes updates, give it the same delay (Dependabot’s cooldown block, Renovate’s minimumReleaseAge). The RubyGems 4.1 beta adds --cooldown to gem install, gem update and gem outdated as well.

Source pinning. Assign every internal gem to its private server with a source block and give every gem an explicit source, so a public gem with the same name can never replace it (dependency confusion). Bundler 4 enforces unambiguous sources; use https or ssh for git, never git:// or http://.

Auditing for known vulnerabilities. bundler-audit (a community gem, not part of Ruby) checks Gemfile.lock against the ruby-advisory-db database of known vulnerabilities and insecure sources (http:// and git://). It works offline once the database is downloaded. Because it reads the lockfile and not the Gemfile (a common misdescription), an application without a committed Gemfile.lock cannot be audited meaningfully. The executable is bundle-audit, which Bundler also reaches as bundle audit through its plugin-by-executable-name lookup:

Run it in CI so that newly disclosed advisories surface quickly; it can also be wired into Rake (require "bundler/audit/task" and Bundler::Audit::Task.new give rake bundle:audit). Since 2026-10 rubygems.org also shows security warnings (from the OSV database, which includes GitHub advisories and OpenSSF malicious-package reports) on gem version pages; gem install and bundle install do not use them yet, the compact index is announced as the next step. Vulnerabilities in RubyGems itself are listed on the RubyGems CVE page; report vulnerabilities in RubyGems, Bundler or rubygems.org to security@rubygems.org and Ruby vulnerabilities through the Ruby security program, never in a public issue. See Security for the rest of the language-level picture.

Gem signing. RubyGems can sign gems (gem cert) and verify them with a trust policy (gem install -P MediumSecurity, bundle install --trust-policy MediumSecurity), but there is no established chain of trust for certificates, so in practice signing is rarely used. Prefer the layers above. (The 4.1 beta adds post-quantum ML-DSA support to the signing workflow.)

Publishing safely. If you publish gems, your account is part of your users' supply chain:

Source: RubyGems Guides: Security practices, How to delay new gem versions with cooldown, Trusted publishing, Setting up multi-factor authentication and API key scopes

Ruby 4.0 ships RubyGems 4 and Bundler 4 (4.0.3 when 4.0.0 was released on 2025-12-25; 4.0.20 with Ruby 4.0.7, 4.0.23 on the latest release at the time of writing). The major version removed long-deprecated behavior; most of it needs no work in a project that already ran without deprecation warnings under Bundler 2.7. To check beforehand on Bundler 2.7, set BUNDLE_SIMULATE_VERSION=4 or bundle config set --local simulate_version 4: it makes Bundler 2.7 behave like Bundler 4.

Bundler 4: commands and flags. Flags that were silently remembered between runs were removed: bundle install --clean, --deployment, --frozen, --no-prune, --path, --shebang, --system, --without, --with and --binstubs; each now fails with a message that names the configuration to use:

bundle viz was extracted to the officially maintained plugin bundler-graph (the command is now bundle graph) and printed [REMOVED] The viz command has been renamed to graph and moved to a plugin; bundle inject was replaced by bundle add; the --binstubs flag by the bundle binstubs command (bundle binstubs --all for every gem); bundle console is deprecated. bundle with no arguments still ran bundle install in 4.0.20, with a notice that it will show the help in a future release.

Bundler 4: Gemfile and lockfile. New lockfiles include CHECKSUMS by default (existing ones are not changed unless bundle lock --add-checksums asks); source pinning is enforced (one global source, path and git only with a gem option or a block); RUBY VERSION and BUNDLED WITH use two-space indentation and RUBY VERSION drops the patch level; git and path gems are included in vendor/cache by default; Bundler falls back to cached data when it meets network errors during resolution.

Bundler 4: API. Bundler.clean_env, with_clean_env, clean_system and clean_exec are removed (use unbundled_env and friends, or original_env), Bundler.environment is deprecated in favor of Bundler.load, SpecSet#- and SpecSet#<< are gone, and the Capistrano 2 and Vlad deployment helpers were dropped.

RubyGems 4. gem query and gem install --default are removed; deprecated Gem::Specification methods (has_rdoc, default_executable, …​) and Gem::Platform.match are gone (use match_spec? or match_gem?); MAKEFLAGS=-j is added by default for extension builds and gem install -j was introduced; the connection pool grew to 5 parallel connections and the batch size of the dependency API from 50 to 100, which the maintainers report as up to 70 percent faster installs; Gem::Platform and Gem::NameTuple support pattern matching; bundle list --format=json prints JSON; bundle install --no-lock skips the lockfile and --lockfile PATH names it (Gemfile.next, Gemfile.rails81 variants); bundle gem --ext=go scaffolds a Go extension next to the C and Rust ones; Bundler uses did_you_mean for typo suggestions; and cooldown arrived in 4.0.13.

Looking ahead. RubyGems and Bundler 4.1 are in beta (4.1.0.beta2, 2026-10-08) and are expected to ship with Ruby 4.1 on 2026-12-25. The betas announce, among others, a PubGrub resolver for RubyGems, one shared resolver and compact-index client for both tools, a global gem cache shared by RubyGems and Bundler, an opt-in OS credential store, content-addressable gems, --cooldown for gem, a Gemfile override DSL and optimistic constraints written by bundle add and bundle gem. Treat these as previews until 4.1 is released.

Source: Upgrading to RubyGems/Bundler 4, What is new in RubyGems and Bundler 4, Cooldown and 4.1.0.beta2 release notes

bundle doctor reports common problems, bundle env prints the environment for a bug report, bundle install --verbose shows what the resolver and installer do, and gem env shows where RubyGems looks.

Source: RubyGems Guides: Troubleshooting common issues

Differences worth remembering: Ruby’s default is a shared gem home (all projects on one Ruby share installed gems; Bundler picks the locked versions at load time), where Python and JavaScript default to per-project environments; Ruby selects one version per gem for the whole process (as does Go’s single-version-per-major rule), where npm can nest several; and a gem can run code when it is installed (native extension builds through extconf.rb) and, through rubygems_plugin.rb files, whenever the gem command starts, as packages in most ecosystems can.