Jekyll One

Fulltext Search

The Cheatsheet discusses RubyGems commands for daily use. RubyGems is a package manager for the Ruby programming language. It provides a convenient way to distribute and manage software packages, called GEMs. With RubyGems, developers can easily install, uninstall, and manage Ruby libraries and applications. It simplifies obtaining and managing the dependencies needed for a Ruby project by automatically resolving and installing the GEMs required.

5 Minutes to read

Introduction

The term gem is related to the tool provided by RubyGems. GEM (capital letters) means the library to be managed by the command gem at the command line.

RubyGems also provides a centralized repository, the RubyGems website at rubygems.org, where developers can publish their GEMs for others to use. The website serves as a searchable catalog of available GEMs, allowing developers to discover and download GEMs for their projects.

In addition to the default RubyGems repository, developers can configure their own GEM sources or specify alternative sources when installing GEMs. This flexibility allows private GEM repositories or custom sources to be used as needed.

RubyGems comes pre-installed with a Ruby installation. It provides a command-line interface, the gem command, for performing various operations, such as installing GEMS, listing installed libraries, updating GEMs, and managing library sources.

Here are common commands you can use with the RubyGems gem command:

  • install  — Installs a GEM from the default RubyGems repository

  • uninstall  — Uninstalls a GEM

  • update  — Updates installed GEMs to their latest versions

  • search  — Searches for GEMs matching a specific term

  • list  — Lists all installed GEMs

  • info  — Provides information about a specific GEM

  • cleanup  — Removes old versions of installed GEMs, keeping only the latest version

The following examples give you an overview of the most common used commands managing Ruby GEMs for daily use. All examples are focussing on the J1 Template to make it easier for users using the template system. Anyway, all commands can be used for any Ruby Application by simply replacing the name of the GEM as required.

Install commands

The install command installs software packages (libraries) in the Ruby programming language. The command will then search for the GEM specified on the RubyGems website (or a different GEM repository configured), download it, and finally install it on your system.

Install from a Gemfile

Add this line to your application’s Gemfile:

gem 'j1-template', '~> 2026.1.3'

and install the locally created RubyGem as:

gem install --local j1-template --no-document

Install globally

Installing a GEM globally makes it available to every user and every Ruby project on your computer. The GEM is stored in the system-wide GEM folder, so you normally need administrator rights to run the command: sudo on Linux and macOS, or a command line started as Administrator on Windows. A global install is a good choice if you always want to work with one single version of a GEM.

gem install j1-template

Install with no docs

By default, RubyGems builds the offline documentation (rdoc and ri) for every GEM it installs. Building this documentation takes time and disk space, and most people read the documentation online anyway. The option --no-document skips that step and makes the installation noticeably faster.

gem install j1-template --no-document

Install userized

A userized install places the GEM in your own home folder instead of the system-wide GEM folder. Because no system folders are written, you do not need administrator rights. This keeps the Ruby installation of your system untouched and is the recommended way to install GEMs if you share the computer with others or are not allowed to modify system files.

When you use the --user-install option, RubyGems will install the GEMs to a directory inside your home directory under ~/.gem/ruby/3.1.0 for Ruby version 3.1.x. The commands provided by the GEMs you have installed will end up in folder ~/.gem/ruby/3.1.0/bin.

gem install j1-template --user-install --no-document

For GEMs installed userized that contain programs, you need to add the folder ~/.gem/ruby/3.1.0/bin to your PATH environment variable to get access.

Install a specific version

If no version is given, RubyGems always installs the newest GEM available. Use the option -v (or --version) to install one specific version instead. This is helpful to keep a project running on a version you have already tested, or to go back to an older version if a newer one causes trouble.

gem install j1-template -v 2026.1.3 --user-install --no-document

You can also use version comparators like >= or ~>.

gem install j1-template -v "~> 2026.1.3" --user-install --no-document

Install from a different source

By default, GEMs are downloaded from the official RubyGems repository at rubygems.org. Use the option --source to load a GEM from a different repository, for example a private or a pre-release server. The given repository is used for this single command only; your permanent source settings stay unchanged.

gem install j1-template -v 2026.1.3 --source 'new_source' --user-install --no-document

Uninstall commands

The uninstall command removes a GEM you no longer need from your system. If more than one version is installed, RubyGems asks you which version should be removed. Use the option -v to remove exactly one version, or --all to remove all installed versions at once. If other GEMs still depend on the GEM to be removed, RubyGems warns you before it continues.

gem uninstall j1-template
gem uninstall j1-template -v 2026.1.3
gem uninstall j1-template --all

Add the option --user-install if the GEM was installed userized into your home folder.

Update commands

The update command replaces installed GEMs by their newest available version. Called without a name, all GEMs installed on your system are updated, which may take a while. Naming a GEM keeps the update small and predictable. Note that an update does not remove the previous version of a GEM. Older versions stay on your system until you remove them with the cleanup command.

gem update j1-template
gem update

Search commands

The search command looks for GEMs whose name contains the text you enter and lists them together with the versions available. The search is done on the RubyGems website, so an internet connection is needed. Use the option --all to see all published versions of a GEM, not only the newest one.

gem search j1-template
gem search j1-template --all

List commands

The list command shows the GEMs that are installed on your computer together with their version numbers. No internet connection is needed. Given a name or only a part of a name, the output is limited to the matching GEMs, which is handy if many GEMs are installed.

gem list
gem list j1-template

Info commands

The info command prints the details of a single GEM: the version installed, a short summary, the homepage, the author, the license, and the folder the GEM was installed to. Use it to find out quickly which version is in use and where it is stored. The option --remote shows the data published on the RubyGems website instead of your local installation.

gem info j1-template
gem info j1-template --remote

Cleanup commands

Every time a GEM is updated, the version installed before stays on your system. Over time, these outdated versions use a lot of disk space. The cleanup command removes them and keeps the newest version only. It is a safe housekeeping task: versions that are still needed by another GEM are not deleted.

Clean up old GEM versions

To clean up old versions on your GEM_PATH of installed gems use below command:

gem cleanup <GEMNAME …>

The cleanup command removes old versions of gems from GEM_HOME that are not required to meet a dependency. If a gem is installed elsewhere in GEM_PATH the cleanup command won’t delete it.

If no gems are named all gems in GEM_HOME are cleaned.

Update Rubygems

gem install rubygems-update
update_rubygems
gem update --system