Configuration (.gemrc)

Where the gem command reads its configuration, and the options a .gemrc file accepts.

The gem command works fine with no configuration at all. A gemrc file exists to change defaults you would otherwise repeat on every invocation, such as disabling documentation generation or adding a private gem server.

Files and precedence

RubyGems merges configuration from several places. Later entries override earlier ones:

Defaults set by the operating system packager and the Ruby implementation.
The system-wide file, gemrc in the system configuration directory, typically /etc/gemrc.
The user file, ~/.gemrc. When that file does not exist, RubyGems reads $XDG_CONFIG_HOME/gem/gemrc instead, which is usually ~/.config/gem/gemrc.
Files listed in the GEMRC environment variable, separated by : on Unix and ; on Windows.

gem --config-file FILE reads a specific file in place of the user file, and gem --norc ignores gemrc files entirely.

Format

A gemrc file is a YAML hash with two kinds of keys. Symbol keys, written with a leading colon, set RubyGems options. String keys naming a gem command set default command-line arguments for that command, and the special key gem sets default arguments for every command.

:sources:
- https://rubygems.org/
:backtrace: true
:concurrent_downloads: 16
install: --no-document
update: --no-document

With this file, gem install rails behaves as if you had typed gem install rails --no-document. Arguments given on the command line are appended after the defaults.

Options

These are the symbol keys RubyGems understands, with their built-in defaults.

Key	Description
`:sources`	Array of gem server URLs that gems are installed from. Default: `https://rubygems.org/`.
`:backtrace`	Print a full backtrace when the gem command hits an error. Default: `true`.
`:verbose`	Output level. `false` is quiet, `true` is normal, and any other value such as `:really` enables extra output. Default: `true`.
`:update_sources`	Update repository metadata automatically. Default: `true`.
`:concurrent_downloads`	Number of gem downloads performed in parallel. Default: `8`.
`:cert_expiration_length_days`	Validity period, in days, of certificates created or re-signed by `gem cert`. Default: `365`.
`:install_extension_in_lib`	Install built extensions into the gem’s `lib` directory as well as the extension directory. Default: `true`.
`:ipv4_fallback_enabled`	Experimental. Fall back to IPv4 when IPv6 is unreachable or slow. Default: `false`.
`:global_gem_cache`	Cache downloaded `.gem` files in one directory shared across all Ruby installations, `~/.cache/gem/gems` by default. Default: `false`.
`:use_psych`	Parse gemrc and other RubyGems YAML files with Psych instead of the built-in minimal YAML parser. Default: `false`.
`:prevent_update_suggestion`	Never suggest running `gem update --system` when a newer RubyGems is available.
`:disable_default_gem_server`	Require an explicit `--host` when pushing gems instead of defaulting to RubyGems.org.
`:gemhome`	The directory gems are installed into. More commonly set with the `GEM_HOME` environment variable.
`:gempath`	Array of directories searched for installed gems. More commonly set with the `GEM_PATH` environment variable.
`:ssl_verify_mode`	OpenSSL verification mode for HTTPS connections to gem servers.
`:ssl_ca_cert`	Path to a CA certificate file or directory used for HTTPS connections.
`:ssl_client_cert`	Path to a client certificate used for HTTPS connections that require client authentication.

API keys for pushing gems are not stored in gemrc. They live in a separate credentials file, ~/.gem/credentials. See API key scopes for how keys are created and scoped.

Bundler is configured separately through bundle config, and its settings do not come from gemrc. See bundle config.

< Previous Next >