Installation Guide

Learn how to install and configure gem on your system

guide

RubyGems is the official package manager for Ruby and is bundled with Ruby 2.7 and newer. If you’re working on Linux, macOS, or Windows, you can install and configure RubyGems in a few straightforward steps. This guide walks you through the essentials—prerequisites, installation, updating, configuration, and common troubleshooting—so you can get your Ruby projects up and running quickly.

1. Prerequisites

  • Install Ruby itself. On Linux you can use your distribution’s package manager:
    • apt install ruby (Debian/Ubuntu)
    • yum install ruby (CentOS/RHEL)
    • dnf install ruby (Fedora)
    • brew install ruby (macOS)
      On Windows, download and run RubyInstaller, which includes RubyGems.
  • Verify that the ruby and gem commands are in your PATH.

2. Verify RubyGems Installation
Run gem --version. If RubyGems is bundled with your Ruby installation, this will print the current version. If you see an error, you’ll need to install RubyGems manually.

3. Installing RubyGems Manually

  1. Download the latest tarball from https://rubygems.org/pages/download.
  2. Extract and run the setup script:
    tar -xzf rubygems-.tgz
    cd rubygems-
    ruby setup.rb
    This installs the gem executable and the core libraries.

4. Updating RubyGems
Keep RubyGems current with gem update --system. On Linux/macOS you may need to prepend sudo. This pulls the latest release and updates your local installation.

5. Configuring RubyGems

  • Global configuration: Edit or create ~/.gemrc (or %USERPROFILE%\.gemrc on Windows). A typical file might contain:
    :backtrace: false
    :bulk_threshold: 1000
    :sources:
  • Per‑project configuration: Use a Gemfile with Bundler to lock gem versions and manage dependencies.
  • Environment variables:
    • GEM_HOME – directory where gems are installed.
    • GEM_PATH – colon‑separated list of gem directories.
    • GEM_SOURCE – override the default source URL.
    • GEM_HTTP_PROXY – set a proxy if you’re behind a firewall.

6. Using Bundler
Bundler simplifies dependency management. Install it with gem install bundler. Then, in your project directory:
bundle init # creates a Gemfile
bundle install
Bundler reads the Gemfile, resolves dependencies, and installs gems into a local vendor/bundle directory if you configure it to do so.

7. Common Troubleshooting

  • Permission errors: On Linux/macOS, prepend sudo or use --user-install to install gems locally.
  • Missing gem command: Ensure the Ruby installation’s bin directory is in your PATH.
  • SSL errors: Update your system’s CA certificates or temporarily disable SSL verification with gem config --local ssl_verify_mode 0 (not recommended for production).
  • Outdated RubyGems: Run gem update --system or reinstall.

8. Uninstalling RubyGems
If you installed RubyGems via a package manager, remove it with the same tool (e.g., apt remove ruby-gems, brew uninstall ruby). If you installed it manually, delete the gem executable and the rubygems directory under Ruby’s lib/ruby/gems.

9. Advanced Configuration

  • Custom gem sources: Add additional sources in ~/.gemrc or with gem sources --add.
  • Gem caching: Use gem install --cache-dir to store downloaded gems locally.
  • Precompiled binaries: Force Ruby source installation with gem install --platform ruby if native extensions fail.

10. Resources for Deeper Learning

With these steps, you’ll have a fully functional RubyGems setup, ready to manage gems for any Ruby project. Happy coding!