RubyGems Navigation menu


Extensions that use the RubyGems plugin API.

RubyGems will load plugins in the latest version of each installed gem or $LOAD_PATH. Plugins must be named ‘rubygems_plugin’ (.rb, .so, etc) and placed at the root of your gem’s #require_path. Plugins are installed at a special location and loaded on boot.

Make your own plugin

The first step is to follow the conventional file name, we will use ruby for this example and check that our plugin is loaded correctly:

% cat lib/rubygems_plugin.rb
puts 'hello from my plugin!'

% RUBYOPT=-Ilib gem
hello from my plugin!
RubyGems is a sophisticated package manager for Ruby.  This is a
basic help message containing pointers to more information.


Of course, our plugin would better be packaged as a gem, which is described in detail in the make your own gem guide.


RubyGems provides various hooks we can use to add custom features and even modify how RubyGems behaves. For example, existing hooks allow executing code before a single gem is installed, after it’s built, after it’s installed, after all gem are installed and many others (see code and documentation for Gem as a reference).

Let’s consider a simple example plugin that would ask confirmation interactively before installing gems while supporting a whitelist. We will leverage the pre_install hook, passing a block to Gem.pre_install method. Reading this method documentation, we learn that our hook will be called with a Gem::Installer instance, and that we can return false to abort the installation:

% cat lib/rubygems_plugin.rb
WHITELIST_PATH = "#{ENV['HOME']}/.gem/install_audit/whitelist"

Gem.pre_install do |installer|
  gem_name =
    whitelist = if File.exist? WHITELIST_PATH

  unless whitelist.include? gem_name
    print "`#{gem_name}' is not whitelisted, install? (y/n): "
    case choice = $stdin.gets.chomp
      when /\Ay/i
      when /\An/i then next false
      else fail "cannot understand `#{choice}'"

% echo rake > ~/.gem/install_audit/whitelist

% RUBYOPT=-Ilib gem install hoe
Fetching: rake-12.3.0.gem (100%)
Successfully installed rake-12.3.0
Fetching: hoe-3.16.2.gem (100%)
`hoe' is not whitelisted, install? (y/n): y
Successfully installed hoe-3.16.2
2 gems installed

% RUBYOPT=-Ilib gem install pry
Fetching: coderay-1.1.2.gem (100%)
`coderay' is not whitelisted, install? (y/n): n
ERROR:  Error installing pry:
  pre-install hook at /…/lib/rubygems_plugin.rb:3 failed for coderay-1.1.2

As expected, RubyGems calls our hook before each gem installation, and when our hook returns false, it aborts with an explanation.

If you find that the plugin system API lacks the extension point you need for your needs, please read CONTRIBUTING.rdoc in RubyGems source code, or see the contributing guide.


Some plugins also add their own commands to the RubyGems CLI. As an example, the graph plugin listed below registers its own graph command this way:

require 'rubygems/command_manager'

Gem::CommandManager.instance.register_command :graph

And implement the command similarly to this:

require 'rubygems/command'

class Gem::Commands::GraphCommand < Gem::Command
  def initialize
    super 'graph', 'Graph dependency relationships of installed gems'

  def execute
    # [real command implementation removed for this guide]

We can then use it by executing gem graph, and it is also documented like other RubyGems builtin commands (gem help commands, gem help graph…).

Existing plugins

The following list of RubyGems plugins is probably not exhaustive. If you know of plugins that we missed, feel free to update this page.


Extends rubygems to support executables plugins.

In gem lib dir create rubygems_executable_plugin.rb:

Gem.execute do |original_file|
  warn("Executing: #{original_file}")


Adds four commands:

  • gem edit opens a gem in your editor
  • gem open opens a gem by name in your editor
  • gem clone clones a gem from GitHub
  • gem browse opens a gem’s homepage in your browser


Adds command gem empty to remove all gems from current GEM_HOME.


Adds a gem ctags command to invoke the Exuberant Ctags indexer on already-installed gems, and then automatically invokes it on gems as they are installed.


Adds a gem info command with fuzzy matching on name and version. Designed for scripting use.


Adds gem init to create a barebones gem.


Adds gem compare command that can help you to track upstream changes in the released .gem files by comparing gemspec values, gemspec and Gemfile dependencies and files.


The gem man command lets you view a gem’s man page.


Tries to install system dependencies needed to install your gems with binary extensions using standard gem install command. This currently works only for Fedora, but hopefully will be extended.


Adds a gem orphan command that finds and lists gems on which no other gems are depending.


Adds gem patch command, which enables you to apply patches directly on .gem files. Supports both RubyGems 1.8 and RubyGems 2.0.


Adds six commands:

  • gem open - opens a gem in your default editor
  • gem cd - changes your working directory to the gem’s source root
  • gem readme - locates and displays a gem’s readme file
  • gem history - locates and display’s a gem’s changelog
  • gem doc - Browse a gem’s documentation in your default browser
  • gem visit - Open a gem’s homepage in your default browser


Create gem wrappers for easy use of gems in cron and other system locations. By default wrappers are installed when a gem is installed.

Adds this commands:

  • gem wrappers regenerate - force rebuilding wrappers for all gem executables
  • gem wrappers - show current configuration


Adds a gem graph command to output a gem dependency graph in graphviz’s dot format.


Adds gem maven to install any Maven-published Java library as though it were a gem.


Exposes manpages inside of a gem to the man command without the need to call gem man or another command to read the man page of a gem.


Adds two commands:

  • gem open opens a gem in your default editor
  • gem read opens a gem’s rdoc in your default browser


Applies a whitelist to gem push to prevent accidentally pushing private gems to the public RubyGems repository.


Automatically runs rbenv rehash after installing or uninstalling gems.

This plugin is deprecated since its behavior is now included in rbenv core.


Adds gem desc to describe a gem by name.


Adds commands and flags to allow OpenPGP signing of gems.

  • gem sign foo.gem to sign a gem.
  • gem verify foo.gem --trust to verify a gem.
  • gem build foo.gemspec --sign to sign at build time.
  • gem install foo --verify --trust to verify on install.


Manages command-line gem tools and dependencies with a gem sandbox command. This lets you install things like flay and rdoc outside of the global rubygems repository.


Adds gem snapshot to create exports of all your current gems into a single file that you can import later.


Allows you to install an “edge” gem straight from its GitHub repository, or install one from an arbitrary web URI.


rubygems-tasks provides agnostic and unobtrusive Rake tasks for building, installing and releasing Ruby Gems.


rubygems_plugin_generator is a plugin that generates plugins. Just run gem plugin <name> and you are good to go.