How to Disable RI and RDoc by Default for gem install in Ruby

By the end of this page, you will understand how RubyGems command defaults work, how to configure gem install to skip documentation automatically, and where to place that configuration so it applies consistently on your machine or server.

RubyGems allows you to define default command-line options in a configuration file. This is useful when you repeatedly use the same flags with gem install.

In this case, the underlying concept is tool configuration through a user or system config file. Instead of remembering to type the same command options every time, you store them once in RubyGems configuration.

Historically, RubyGems generated RI and RDoc documentation for installed gems. If you do not use those local docs, disabling them can:

• save installation time
• reduce disk usage
• keep commands shorter
• make server setup scripts more predictable

The main idea is that gem install behavior can be customized globally by editing the .gemrc file.

A common configuration looks like this:

gem: --no-ri --no-rdoc

On newer RubyGems versions, documentation handling changed, and a more modern option is often:

gem: --no-document

So the broader lesson is not only about RI and RDoc. It is about understanding that many developer tools support persistent defaults through configuration files.

Think of gem install like a machine with buttons.

Normally, every time you use it, you press extra buttons such as "skip docs". That works, but it is repetitive.

A config file is like changing the machine's default settings once, so every future use starts the way you prefer.

Instead of saying:

• "Install this gem"
• "Also skip RI"
• "Also skip RDoc"

...every single time, you tell RubyGems:

• "Whenever I install gems, assume I want docs skipped unless I say otherwise."

That is the purpose of .gemrc: storing your preferred defaults.

RubyGems reads settings from a YAML configuration file named .gemrc.

Basic configuration

For older RubyGems versions:

gem: --no-ri --no-rdoc

For newer RubyGems versions:

gem: --no-document

Where to put it

A common user-level location is:

~/.gemrc

Example:

echo 'gem: --no-document' >> ~/.gemrc

Or manually create/edit the file:

gem: --no-document

What this does

After saving the config, this command:

gem install rails

behaves more like:

gem install rails --no-document

without you having to type the flag every time.

Example workflow

cat ~/.gemrc

Output:

gem: --no-document

Then install a gem:

gem install bundler

RubyGems reads the config and skips documentation generation automatically.

Consider this setup:

gem: --no-document

stored in:

~/.gemrc

Now run:

gem install rake

Step-by-step

1. RubyGems starts the install command.

2. It checks its configuration sources, including your .gemrc file.

3. It finds the line:

   gem: --no-document
   

4. RubyGems applies that option as a default for gem commands.

5. The rake gem is downloaded and installed.

6. Documentation generation is skipped.

7. The install finishes faster and uses less space.

Older version trace

If your RubyGems version expects older flags, this config may be used:

gem: --no-ri --no-rdoc

The process is the same. The difference is only the specific option name RubyGems understands.

Local development machines

Developers often install many gems while switching projects. Skipping RI and RDoc avoids repeated wasted time if local docs are never used.

CI and build servers

Continuous integration environments should be fast and minimal. Disabling documentation reduces setup time during dependency installation.

Production servers

Servers usually do not need local gem documentation. Keeping installs lean helps reduce disk usage and deployment noise.

Container images

When building Docker images for Ruby apps, every unnecessary file increases image size. Skipping docs helps keep images smaller.

Provisioning scripts

Automation tools such as shell scripts, Ansible, or Chef benefit from predictable defaults. A .gemrc file avoids repeating flags in every script.

In real projects, developers usually combine this idea with broader environment setup practices.

Common patterns

Developer machine bootstrap

A setup script may create ~/.gemrc during onboarding:

echo 'gem: --no-document' > ~/.gemrc

This ensures every developer gets the same default behavior.

Server provisioning

Infrastructure scripts often add RubyGems config as part of machine preparation so deploys and maintenance tasks are faster.

Minimal Docker environments

A Dockerfile may include a RubyGems configuration step before installing dependencies.

Configuration over repetition

Instead of writing:

gem install bundler --no-document
gem install rake --no-document
gem install rspec --no-document

teams prefer one config file and shorter commands:

gem install bundler
gem install rake
gem install rspec

Related coding habit

This reflects a broader programming practice: move repeated options into configuration when they represent a stable default.

1. Using old flags on a newer RubyGems version

Older examples often show:

gem: --no-ri --no-rdoc

On newer RubyGems versions, the preferred option is usually:

gem: --no-document

If the old flags do not work, check your RubyGems version and use the newer option.

2. Writing invalid YAML

Broken example:

gem --no-document

This is invalid because YAML needs a key-value structure.

Correct:

gem: --no-document

3. Editing the wrong file

Some users change shell config files like .bashrc or .zshrc expecting RubyGems to read them automatically.

RubyGems uses .gemrc, not your shell profile, for this setting.

4. Expecting system-wide behavior from a user config

~/.gemrc usually affects only the current user. If you manage multiple users or automated system accounts, each context may need its own configuration.

5. Assuming all environments use the same RubyGems version

A local machine, CI server, and production server may have different RubyGems versions. One environment may expect --no-ri --no-rdoc, while another expects --no-document.

6. Forgetting that command-line options can override defaults

Even with .gemrc, explicit flags passed on the command line may change behavior for a specific install.

Old flags vs new flag

Configuration vs repeating commands

# Older RubyGems
gem: --no-ri --no-rdoc

# Newer RubyGems
gem: --no-document

# Typical config file location
~/.gemrc

# Example: create/update config
printf 'gem: --no-document\n' > ~/.gemrc

Rules to remember

• Use .gemrc to store default RubyGems options.
• Use --no-document on newer RubyGems versions.
• Use --no-ri --no-rdoc only if your RubyGems version still expects them.
• .gemrc is usually per-user, not automatically global.
• The config file uses YAML syntax.

Quick check

cat ~/.gemrc

Expected content:

gem: --no-document

How do I stop gem install from generating documentation by default?

Create or edit ~/.gemrc and add:

gem: --no-document

Should I use --no-ri --no-rdoc or --no-document?

Use --no-document on newer RubyGems versions. Use --no-ri --no-rdoc only if you are working with an older setup.

Where is the RubyGems config file located?

For a user-specific setup, it is commonly located at ~/.gemrc.

Does this affect all users on a server?

No, not usually. A file in ~/.gemrc applies to the current user account.

Can I still install documentation for one gem later?

Yes. Defaults are just defaults. You can override behavior with command-line options when needed.

Why would developers disable gem documentation?

Usually to save installation time, reduce disk usage, and simplify automated environments.

Is this safe for production servers?

Yes, if you do not rely on locally generated gem docs on that server.

• RubyGems configuration — directly related because .gemrc controls default gem command behavior.
• YAML syntax — important because .gemrc uses YAML key-value formatting.
• Command-line flags — this topic starts with repeated use of CLI options like --no-document.
• Environment setup — disabling docs is often part of configuring development machines and servers.
• Dependency management in Ruby — gem installation behavior affects how Ruby dependencies are installed and maintained.
• Bundler — commonly used alongside RubyGems in real Ruby projects, though it solves a different problem.
• Automation and provisioning — .gemrc is often created automatically in setup scripts or server provisioning workflows.