A comprehensive guide to finding, creating and using Ruby resources called gems.

RubyGems is a system for managing Ruby software libraries. Ruby code packaged in this manner is called a gem. When you find Ruby software you want to use in a project, gems offer a means of downloading, installing and managing the software.


Ruby's connection with Perl caused converts to ask an obvious question “Where is the CPAN (Comprehensive Perl Archive Network) for Ruby?” If you have done any Perl programming or used Perl software, you likely have downloaded something from CPAN to make the software work. As it is the de facto standard for sharing libraries in Perl, access to CPAN makes it easier to re-use code developed by others. This tool allows the developer to focus on new problems instead of re-inventing the wheel.

As it turns out, package management is not as simple as it sounds. It gets even more complicated when you are trying to solve a problem for a variety of platforms and operating systems (Ruby runs on a *nix/*BSD/Mac OS X/WinX). There have been several attempts at building a working system.

Ryan Leavengood is credited with creating the very first RubyGems project back in 2001 (see the on-line Resources). The project got started but did not really gain enough momentum to take off. Other solutions were attempted, but they did not really catch on enough to dominate the field.

In November 2003, Rich Kilmer, Chad Fowler, David Black, Paul Brannan and Jim Weirch got together at a Ruby conference and started coding. Their goal was to create a solution once and for all. They obtained permission to use the existing name RubyGems from Leavengood, even though they did not use any code from the previous project.

RubyGems set out to solve several problems. The focus was on simplifying the process of installing, removing, updating and managing Ruby libraries. The developers added an interesting twist by allowing the system to manage multiple versions of the same library easily.Using the versioning scheme from RubyGems, it is possible to provide very powerful control over the selection of which version of a library your code will actually use.

Getting Started

There are plans to include RubyGems as part of the core distribution of Ruby, but until that happens, you need to install it. Your Linux distribution may have a package (RPM, Deb and so on) for RubyGems. In the event that it does not, you can install it from source easily, assuming you have Ruby and the development headers for Ruby already installed on your Linux box.

You can do the following as a user: go to, and download the current version (0.8.11 at the time of this writing):

tar xzf rubygems-0.8.11.tgz
cd rubygems-0.8.11

You must be root to install the software (assuming you want it to be available to all users):

ruby setup.rb all

Now that RubyGems is installed, you should have the gem command (gem is the command used to interact with the RubyGems package system). Test it out by running:

gem list

It should show a single package—sources (0.0.1) installed. The gem command is the way you interact with the RubyGems package system.

User Tasks

Now that you have the gem command, you can begin installing gem packages. You need to be root to install or modify gems, but any user can query the system to find out what is installed. When you want to find software, you can always check out RubyForge (see Resources). It is the main clearinghouse for Ruby open-source software.

One of the most popular RubyForge projects is Ruby on Rails. The Rails gem (and the gems it depends on) can be installed with the following command:

gem install rails --include-dependencies

Another very popular project is RMagick. RMagick is a useful Ruby interface to ImageMagick (see Resources), and it can be installed with the following command:

gem install rmagick

This gem includes non-Ruby code. When you install it, it will compile the C code as part of the installation process. If you do not have compile tools installed, the installation will fail.

RubyGems features a number of useful features, including:

gem search rails --remote

This returns a list of all the packages and versions available on RubyForge that have the word rails in the title of the package. Here are a few more, well, er, gems:

  • gem update: updates all the current versions of gems to their latest version.

  • gem cleanup: removes old versions of gems that are installed.

  • gem uninstall: removes a given gem from the repository.

Because I try to keep up with the most current version of the gem software, I usually gem update and then gem cleanup the repository to get rid of old libraries. Doing this keeps the gems directory a little cleaner and makes it easier to sort through if and when you need to look in the directory.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

the option --include-dependencies is the default

Jian Lin's picture

gem install rails --include-dependencies

can be

gem install rails



is now the default on the current gem 1.3.7


Anonymous's picture

Thank you for this article, posted on May 27, 2006 and still helping people!;)

nice stuff

Kanuverleih's picture

Thank You for another very interesting article.
It’s really good written and I fully agree with You
on main issue, btw. I must say that I really enjoyed
reading all of Your posts. It’s interesting to read ideas,
and observations from someone else’s point of view… it makes
you think more. So please try to keep up the great work all the time.