How to Install a Specific Version of a Ruby Gem

By the end of this page, you will understand how to install a specific version of a Ruby gem from the command line, why version pinning matters, what command syntax to use, and how this fits into real Ruby projects and dependency management.

In Ruby, gems are reusable packages that add functionality to your application or development environment. When you run gem install some_gem, RubyGems usually installs the latest available version.

Sometimes, however, you need a specific version instead of the newest one. This is common when:

• your project depends on an older version
• a newer release introduced breaking changes
• you need to match a production environment
• you are debugging version-specific behavior

RubyGems lets you choose a version explicitly with the --version option.

gem install GEM_NAME --version VERSION

Example:

gem install rails --version 7.0.8

This tells RubyGems to install exactly that version if it is available.

This matters because software versions affect compatibility. Even small changes between gem versions can change APIs, behavior, performance, or dependency requirements. Installing a specific version makes your environment more predictable and reproducible.

Think of a gem like a textbook that gets new editions over time.

• gem install rails means: “Give me the newest edition.”
• gem install rails --version 7.0.8 means: “Give me exactly edition 7.0.8.”

If your class assignments were written for edition 7.0.8, using edition 8.0.0 might cause confusion because page numbers and content may have changed. Gem versions work the same way: the code in your project may expect a particular version.

The core syntax is:

gem install GEM_NAME --version VERSION

You can also use the short form:

gem install GEM_NAME -v VERSION

Example 1: Install an exact version

gem install bundler --version 2.4.22

This installs version 2.4.22 of bundler.

Example 2: Short version flag

gem install rake -v 13.1.0

This does the same thing using the shorter -v option.

Example 3: Check installed versions

After installing, you can list installed gems:

gem list rake

Possible output:

rake (13.1.0, 13.0.6)

This means multiple versions may exist on your system.

Example 4: Install without documentation

gem install rspec -v 3.12.0 --no-document

This installs the chosen version and skips local documentation generation, which can make installation faster.

Example 5: Version constraints

RubyGems can also accept version constraints:

gem install rails -v '~> 7.0.0'

This means install a version compatible with 7.0.x, depending on what is available.

For beginners, the most important form is the exact version:

gem install GEM_NAME -v X.Y.Z

Consider this command:

gem install nokogiri -v 1.15.5

Here is what happens step by step:

1. The gem command starts the RubyGems command-line tool.
2. install tells RubyGems you want to install a package.
3. nokogiri is the gem name.
4. -v 1.15.5 tells RubyGems to look for that specific version.
5. RubyGems checks available gem versions from the configured source, usually RubyGems.org.
6. If version 1.15.5 exists and is compatible with your Ruby environment, RubyGems downloads it.
7. RubyGems also installs any required dependencies.
8. The gem becomes available in your Ruby environment.

You can then verify it with:

gem list nokogiri

If you see output like this:

nokogiri (1.15.5)

then the installation worked.

If the version does not exist, RubyGems will report an error instead of silently installing a different version.

Installing a specific gem version is common in real development work.

Maintaining older applications

A legacy Rails app may only work with an older version of rails, devise, or sidekiq.

gem install rails -v 6.1.7

Matching production environments

If production uses a specific Bundler version, developers often install that same version locally.

gem install bundler -v 2.3.26

Reproducing bugs

If a bug happens only in one gem version, you may install that version to test it.

gem install pg -v 1.4.6

CI and deployment scripts

Build scripts sometimes install exact tool versions for predictable results.

Safe upgrades

Teams often test a new gem version gradually rather than always jumping to the latest release.

In real projects, developers usually do not manually install every application dependency one by one. Instead, they use Bundler with a Gemfile to declare versions.

Example Gemfile:

gem 'rails', '7.0.8'
gem 'pg', '~> 1.5'
gem 'puma'

Then they run:

bundle install

Still, gem install -v is commonly used for:

• installing a specific version of bundler
• installing CLI gems globally
• testing a gem version outside a project
• setting up tooling on CI servers

Common patterns in codebases

• Version pinning: lock exact versions for stability
• Compatible ranges: allow safe updates with constraints like ~>
• Environment matching: install the same version across local, CI, and production
• Debugging: compare behavior across gem versions

Guarding against environment problems

Teams often check tool versions before running scripts:

bundle --version
ruby --version

This helps ensure the installed gem version matches project expectations.

1. Forgetting the version flag

Broken command:

gem install rails 7.0.8

Why it is wrong:

• RubyGems does not treat the extra value as the version in this form.

Correct command:

gem install rails -v 7.0.8

2. Assuming the latest version will always work

Beginners often install the newest version and expect compatibility with older code.

gem install some_gem

Avoid this when a project requires a known version.

3. Confusing gem install with Bundler

gem install installs gems into your Ruby environment.

bundle install installs dependencies from a Gemfile for a project.

If you are working inside an application, check whether the project expects Bundler instead.

4. Using a version that does not exist

gem install rake -v 99.99.99

This fails because that version is not published.

You can inspect available versions with:

gem search '^rake$' --remote --all

5. Ignoring Ruby version compatibility

Some gem versions require a newer or older Ruby version. If installation fails, the problem may not be the gem command itself.

Check your Ruby version:

ruby --version

6. Forgetting that multiple versions can be installed

You may install a specific version successfully and still have other versions on the system. That does not always mean the exact one will be used automatically in every context.

Use tools like Bundler to control which version a project runs.

gem install vs bundle install

Exact version vs version range

# Install an exact version
gem install GEM_NAME -v X.Y.Z

# Same using long flag
gem install GEM_NAME --version X.Y.Z

# Example
gem install rails -v 7.0.8

# Skip documentation
gem install rails -v 7.0.8 --no-document

# List installed versions
gem list rails

# Search available remote versions
gem search '^rails$' --remote --all

Quick rules

• Use -v or --version to specify a version.
• Use an exact version for predictable installs.
• Multiple gem versions can be installed on one machine.
• In application projects, prefer Bundler and a Gemfile for dependency management.
• If installation fails, check whether the version exists and whether your Ruby version is compatible.

Most important command

gem install GEM_NAME -v VERSION

How do I install a particular version of a Ruby gem?

Use:

gem install GEM_NAME -v VERSION

Example:

gem install rake -v 13.1.0

Can I install multiple versions of the same gem?

Yes. RubyGems can keep multiple versions installed on the same system.

How do I see which gem versions are available?

Use:

gem search '^GEM_NAME$' --remote --all

Example:

gem search '^rails$' --remote --all

What is the difference between -v and --version?

They mean the same thing. -v is just the short form.

Should I use gem install or bundle install?

Use gem install for direct or global installs. Use bundle install when working inside a Ruby project with a Gemfile.

Why did my specific gem version fail to install?

Common reasons include:

• that version does not exist
• your Ruby version is incompatible
• system dependencies are missing
• network or permissions issues occurred

Can I install a version range instead of an exact version?

Yes. Example:

gem install rails -v '~> 7.0.0'

This allows a compatible version rather than one exact release.

• RubyGems — the package manager that provides the gem command.
• Bundler — manages project-specific gem dependencies through a Gemfile.
• Gemfile — the file where Ruby projects declare gem dependencies and versions.
• Semantic Versioning — helps you understand version numbers like 1.2.3.
• Dependency Management — the broader practice of controlling library versions in software projects.
• Ruby Environment — the Ruby installation and gem set available on your machine.
• Version Pinning — locking a dependency to a specific version for stability.