LinuxCommandLibrary

gem

Manage RubyGems packages

TLDR

Search for remote gem(s) and show all available versions

$ gem search [regular_expression] --all
copy

Install the latest version of a gem
$ gem install [gem_name]
copy

Install a specific version of a gem
$ gem install [gem_name] --version [1.0.0]
copy

Install the latest matching (SemVer) version of a gem
$ gem install [gem_name] --version '~> [1.0]'
copy

Update a gem
$ gem update [gem_name]
copy

List all local gems
$ gem list
copy

Uninstall a gem
$ gem uninstall [gem_name]
copy

Uninstall a specific version of a gem
$ gem uninstall [gem_name] --version [1.0.0]
copy

SYNOPSIS

gem [options] [command] [arguments]

Examples:
gem install rails
gem update
gem list --local

PARAMETERS

gem install gemname [options]
    Installs one or more specified gems. Often requires root privileges for system-wide installation.
Example: gem install bundler

gem update [gemname]
    Updates all installed gems or a specific gem to the latest version. This command refreshes your gem versions based on remote sources.
Example: gem update --system (updates RubyGems itself)

gem uninstall gemname [options]
    Removes one or more specified gems from your system. Careful use is advised to avoid breaking dependencies.
Example: gem uninstall rails

gem list [options]
    Lists all installed gems. Can be filtered or display remote gems using various options.
Example: gem list --local

gem search query [options]
    Searches for gems on remote sources (like rubygems.org) matching the given query.
Example: gem search rails --remote

gem build gemspec_file
    Builds a gem package (.gem file) from a gemspec file, which defines the gem's contents and metadata.
Example: gem build my_gem.gemspec

gem push gem_file
    Publishes a built gem (.gem file) to a remote gem host, typically rubygems.org. Requires authentication.
Example: gem push my_gem-1.0.0.gem

gem env
    Displays detailed information about your RubyGems environment, including paths, versions, and configurations.
Example: gem env

gem help [command]
    Provides help information for the general gem command or a specific subcommand.
Example: gem help install

--version
    Displays the current version of RubyGems itself.
Example: gem --version

--help
    Displays general help documentation for the gem command.
Example: gem --help

DESCRIPTION

The gem command is the primary command-line interface for RubyGems, Ruby's standard package manager. It provides essential functionalities for managing Ruby libraries, known as 'gems'. Developers use gem to install, update, uninstall, and list gems, fetching them from remote repositories like rubygems.org. It intelligently handles gem dependencies, ensuring all necessary libraries are installed. Beyond just consumption, gem also empowers gem authors to create, build, and publish their own gems to the community. It is analogous to package managers like pip for Python or npm for Node.js, forming the backbone of the Ruby ecosystem's dependency management.

CAVEATS

When installing gems globally (system-wide), the gem command often requires root privileges (e.g., using sudo), which can be a security concern or lead to permission issues.
While RubyGems handles dependencies, complex projects often benefit from version managers like RVM or rbenv and project-specific dependency tools like Bundler to avoid conflicts and maintain isolated gem environments.
Older versions of RubyGems might have less robust dependency resolution, which could lead to 'gem hell' where incompatible versions clash.

<B>GEMFILE AND BUNDLER INTEGRATION</B>

While gem manages globally installed libraries, projects often use a Gemfile and the bundle command (from the Bundler gem) for managing project-specific dependencies. Bundler ensures that each project uses a consistent set of gem versions, which is crucial for reproducible builds and deployment. gem install bundler is typically the first step to enable this workflow.

<B>GEM SOURCES</B>

By default, gem fetches libraries from rubygems.org, the central repository for Ruby gems. However, it can also install gems from local files, Git repositories, or other custom gem servers configured in the RubyGems environment. This flexibility allows for private gem hosting and development workflows.

HISTORY

RubyGems was created to address the need for a robust package management system in the Ruby ecosystem, similar to Perl's CPAN. Its development began in 2003, with the first official release in 2004. It quickly gained traction and became the de facto standard for distributing Ruby libraries. Over time, RubyGems has improved significantly in dependency resolution and integration with the Ruby interpreter, often shipping as part of the Ruby distribution itself.

SEE ALSO

ruby(1), bundle(1), irb(1)

Copied to clipboard