gem install: Usage, Options & Common CI Errors

gem install downloads and installs a Ruby gem and its dependencies.

gem install adds gems outside of Bundler. In CI the common issues are slow documentation generation, permission errors against the system Ruby, and native-extension build failures.

What it does

gem install fetches a gem from rubygems.org and installs it (with dependencies) into the active Ruby's gem path. Gems with C extensions compile at install time, so they need a toolchain and headers. --no-document skips the slow rdoc/ri generation, which you almost always want in CI.

Common usage

Terminal

gem install bundler --no-document
gem install rails -v 7.1.3 --no-document
gem install nokogiri --no-document               # builds a native extension
gem install --user-install rubocop                # install into ~/.gem

Common errors in CI

"You don't have write permissions for the /usr/lib/ruby/gems directory" (or "Permission denied") happens with system Ruby - use a version manager (rbenv), --user-install, or sudo (least preferred). "ERROR: Failed to build gem native extension" means missing build tools or headers (e.g. nokogiri needs build-essential and sometimes libxml2-dev, though modern nokogiri ships precompiled). "Could not find a valid gem \"X\"" is a wrong name or a network/source problem. --no-document avoids wasting minutes on docs.

Options

Flag	What it does
--no-document	Skip rdoc/ri generation (faster)
-v / --version	Install a specific version
--user-install	Install into the user gem dir (no sudo)
-N	Alias for --no-document
--source <url>	Use a specific gem source