RubyGems and Bundler: installing, managing and publishing Ruby gems

What RubyGems is for, and who ends up using it

RubyGems is the package management framework for Ruby. A package, called a gem, bundles functionality a Ruby program can load, such as reading and parsing an XML file. The framework installs, creates, manages and loads those packages inside a Ruby environment. It is also a client for RubyGems.org, the public repository where gems are published so other developers can install them.

The audience is broader than it first appears. Library authors use the gem command and the publishing guide to ship code. Application developers mostly meet RubyGems indirectly, because Bundler is developed in this same repository and ships with Ruby. Anyone who runs a Ruby program that requires a third-party library is already a user, whether or not they ever type gem directly.

The README frames the split clearly: gem handles installing and managing individual gems, while Bundler makes sure a Ruby application runs the same code on every machine. That division matters when you decide which tool to reach for.

How the gem command and Bundler split the work

The mechanism is a local environment plus a remote index. When you install a gem, RubyGems downloads it from RubyGems.org and places it into your Ruby environment. Your program then loads it with a plain require. That is the whole data flow for a single gem: resolve, download, install, require.

Bundler adds a resolution step on top. Given a list of gems, it downloads and installs those gems plus any gems they themselves need. Before installing, it checks the versions of every gem to make sure they are compatible and can all be loaded at the same time. This is the part a bare gem install does not do for you. After installation, Bundler records the exact versions that were installed, so another machine can install the exact same set. It can also update some or all gems when new versions appear.

The repository layout reflects that pairing: bundler.gemspec and rubygems-update.gemspec sit side by side at the top level, with lib/, exe/, bin/ and setup.rb alongside them. The release policy states that RubyGems and Bundler share a version number and are released together, so a version bump moves both.

Installing RubyGems and running a first gem

In most cases you do not install RubyGems at all. It is already present in your Ruby environment, and the README says to check what you have with:

gem --version

If you need to upgrade to the latest RubyGems, the documented command is:

gem update --system

For a manual installation, download from https://rubygems.org/pages/download, unpack, and cd into the src directory, or clone the repository and cd into it. Then run:

ruby setup.rb

The README notes that setup.rb --help lists more details and options. One warning is worth repeating: the README says OS-packaged Ruby and RubyGems are not a recommended way to use them, and suggests a Ruby version manager such as rbenv or chruby instead. If you do use the OS package, upgrade RubyGems through that same package manager and ignore the manual steps.

With the tool present, installing a library is one line. The README uses Faraday as the example:

gem install faraday

RubyGems downloads Faraday from RubyGems.org and installs it into your Ruby environment. Inside a Ruby program you then load it and use it:

require 'faraday'
response = Faraday.get('https://rubygems.org')

For an application rather than a single library, the README shows the Bundler path with rspec as the example. bundle init creates the Gemfile, bundle add rspec records the dependency, bundle install resolves and installs it, and bundle exec rspec runs the command against the pinned set:

bundle init
bundle add rspec
bundle install
bundle exec rspec

The distinction to hold onto is that gem install puts a library in your environment for any program to use, while the Bundler sequence ties a version set to one application.

Where RubyGems is the wrong tool

The clearest boundary is language. RubyGems manages gems for Ruby, and nothing in the README suggests it resolves dependencies for another runtime. If your project is polyglot, this is one tool among several, not a replacement for the others.

A second boundary is version scope. A bare gem install does not give you the compatibility check and lockfile that Bundler provides. If two gems in an application need conflicting versions of a shared dependency, installing them one by one will not surface that for you. The README describes Bundler as checking versions before installing so they can all load at the same time, which is exactly the check you skip when you stay at the gem level.

Upgrades are the third edge. The README points to doc/UPGRADING.md for details and alternative instructions, and the release policy describes occasional major releases with major breaking changes, alongside yearly minor releases that can include minor breaking changes affecting edge cases. Anyone pinned to an old RubyGems should read that document rather than assume gem update --system is a no-op. The README also states RubyGems supports Ruby 3.0 or later, so older Ruby installations are outside the supported range.

Bundler versus plain RubyGems, and what else people compare

The comparison that matters most is internal. Plain RubyGems answers the question "is this library available in my environment?" Bundler answers "which exact versions does this application need, and are they mutually compatible?" The first is a package installer; the second is a dependency resolver with a recorded result. They are not alternatives so much as layers, and the README treats them that way by describing both in one document.

For an alternative outside the project, the honest answer is that RubyGems is the default distribution channel for Ruby, and the README does not name a competing package manager. What it does name is a different installation route: OS package managers. The README explicitly says that route is not recommended and that a Ruby version manager such as rbenv or chruby is better. That is the real fork in the road for most users, not a choice between two package managers.

If you are evaluating whether to publish through RubyGems.org, the relevant difference is reach rather than features. The README describes RubyGems.org as a public repository that allows you to publish a gem that can be shared and used by other developers, and points to the publishing guide for the mechanics.

Maintenance, release cadence and licence questions

The last push to the repository was on 2026-09-20, and the most recent releases listed are v4.0.21 on 2026-09-16, v4.1.0.beta1 on 2026-09-09 and v4.0.20 on 2026-09-02. The release policy explains the rhythm: frequent patch releases every two to four weeks covering bug fixes, minor enhancements, small features, or medium features declared experimental for testing; yearly minor releases with bigger features and minor breaking changes; and occasional major releases with major breaking changes. RubyGems and Bundler share a version number and ship together, so an upgrade moves both at once.

That cadence sets the upgrade cost. Patch releases should be low risk by design. The yearly and major releases are where you read doc/UPGRADING.md before acting. For application developers, Bundler's lockfile limits the blast radius, because the recorded versions do not change until you update them. For library authors, the exposure is different: your gem's declared version constraints determine what your users get.

On licensing, the repository carries both LICENSE.txt and MIT.txt at the top level, while the metadata reports the licence as NOASSERTION, meaning the repository does not declare a standard SPDX identifier that the tooling can read. Read both files directly before you depend on the terms. This is a description of what the repository contains, not legal advice.

Editorial conclusion

Adopt RubyGems if you write or consume Ruby libraries: it is already in your Ruby environment and `gem update --system` keeps it current, and Bundler in the same repository handles application-level pinning. Do not reach for it when you need a dependency manager for another language, or when you want a fully offline mirror, since the README documents no such mode. Before relying on a specific version, check `gem --version` against the Ruby 3.0 or later requirement, and read doc/UPGRADING.md before any major upgrade, because RubyGems and Bundler share a version number and are released together.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. ruby/rubygems on GitHub