Introduction to RubyGems

RubyGems is a package manager for Ruby code. It's used to organize reusable code into a deliverable known as a "gem." Everyone who has programmed in Ruby or used the Rails framework has probably installed a gem at one time or another. Even the Rails framework is packaged as a set of gems.

The troubling thing is that many Ruby developers, and most Rails developers, are not taking full advantage of the power of gems. This article will explore some of the capabilities of RubyGems and illustrate how those capabilities can be used to support real-world Rails development efforts.

The Basics

RubyGems is the project which produced the well-known gem utility program. It shouldn't surprise anyone that packages created by the utility are known as gems.

A gem has some key characteristics:

  • It contains packaged code.
  • It has a version associated with it.
  • It may have dependencies on other gems.

The gem command can be used to install a gem:

$ gem install will_paginate

The example above installs the most recent version of the "will_paginate" gem.

$ gem install will_paginate --version 2.2.2

This example installs version 2.2.2 of the gem.

But where does RubyGems look to find the gem? The answer is that the gem command has a defined set of well-known locations where it will look for gems. This includes locations such as RubyForge, a free repository of open source Ruby code.

$ gem uninstall will_paginate

This command can be used to uninstall a gem. If there are multiple versions of the gem installed, then the command will prompt for the version to be removed.

$ gem update will_paginate

Update a gem to the latest version. To update all gems, just use "gem update."

RubyGems "Admin" Features

You can do lot more with RubyGems than just install and uninstall gems. The gem command takes advantage of the information associated with each individual gem to make a variety of other features available to users.

$ gem list

This command will display a list of all the gems (including version numbers) that are installed locally. Note that you can have multiple versions of the same gem installed on a computer.

$ gem query --remote

This command will display a list of all the gems that are available remotely from the standard search locations.

$ gem spec will_paginate

Assuming the will_paginate gem is installed locally, this command will print out detailed information from the gem specification, including version, date created, summary, dependencies, the list of files included in the gem, etc.

$ gem environment

The gem command will also show you detailed information about the RubyGems environment. The above command produced the output in Listing 1.

Listing 1: RubyGems Environment
RubyGems Environment:
  - RUBYGEMS VERSION: 1.1.0 (1.1.0)
  - RUBY VERSION: 1.8.6 (2008-03-03
            patchlevel 114) [i686-darwin9.0.0]
  - INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/1.8
  - RUBY EXECUTABLE: /usr/local/bin/ruby
    - ruby
    - x86-darwin-9
     - /usr/local/lib/ruby/gems/1.8
     - :update_sources => true
     - :verbose => true
     - :benchmark => false
     - :backtrace => false
     - :bulk_threshold => 1000
     - :sources => ["",

By viewing the output, developers can discover where the Ruby gems are installed on the local computer as well as other information. For example, the output also shows that the default locations where the gem command searches for gems are RubyForge and

RubyGems Documentation

There is a comprehensive online User Guide available for RubyGems. It can be found at the URL below:

I'd consider the RubyGems User Guide to be excellent if it was completely current. Since it is a little out-of-date in places, I'll downgrade it slightly to good, rather than excellent. Despite a few discrepancies between the content and the current state of RubyGems, it's still a useful manual.


RubyGems has been an extremely successful package. As such, it is now required by Rails 2.0.2 as a dependency. During the boot process, Rails also loads RubyGems, so there's no longer a need for developers to use require statements to load RubyGems. This is not reflected in the online documentation, which indicates in many places the need to load RubyGems. Additionally, be aware that RubyGems options may have also changed since the documentation was written.

If developers are working with Ruby 1.8.6 (as most of us still are, at least for production code), RubyGems will have to be installed in each environment. Beginning with Ruby 1.9, RubyGems will be automatically delivered as part of a Ruby installation.


David Keener By ubolt on Tuesday, June 15, 2010 at 07:09 AM EST

The RubyGems docs are now at available at:

The old RubyGems site has been replaced by the new GemCutter systems, which has now become RubyGems.

Leave a Comment

Comments are moderated and will not appear on the site until reviewed.

(not displayed)