How to Fix RubyGems Permission Errors When Installing Gems in Ruby

By the end of this page, you will understand why RubyGems sometimes fails with a permissions error, what that error means, and the safest ways to install gems. You will also learn the difference between using sudo, installing gems in a user-owned Ruby environment, and using version managers such as rbenv or rvm.

RubyGems installs packages, called gems, into a directory managed by your Ruby installation. The error:

Gem::FilePermissionError

means Ruby is trying to write files into a location your current user does not own.

A common example is the system Ruby that comes preinstalled on macOS:

/Library/Ruby/Gems/2.0.0

That folder is usually protected because it belongs to the operating system. Regular users can read from it, but not write to it.

Why this happens

When you run a command like:

gem install mygem

RubyGems decides where to place the gem files. If your current Ruby installation is the system Ruby, the default gem path may point to a protected system directory.

This creates a conflict:

• gem install needs to write files
• your user account lacks permission to write there
• RubyGems raises a permission error

Why this matters

Understanding this error is important because it affects how you manage Ruby tools on your machine.

In real development, installing gems the wrong way can cause:

• broken system Ruby setups
• conflicts between projects
• hard-to-debug environment issues
• dependence on sudo for everyday development

The long-term best practice is usually to use a Ruby version manager and install Ruby in your home directory, where you have full control.

Think of your computer like an apartment building.

• The system Ruby directory is the building's maintenance room.
• Your normal user account is a resident.
• Residents are not allowed to change tools in the maintenance room.
• gem install is trying to put a new tool into that locked room.

That is why the system says: you do not have permission.

You have three main options:

1. Ask the building manager using sudo.
   • This gives temporary admin access.
   • It works, but it is not always the safest long-term choice.
2. Keep your own toolbox in your home directory.
   • This means installing gems where your user owns the files.
3. Get your own workshop with rbenv or rvm.
   • This is usually the cleanest developer setup.

The key idea is simple: the error is not about the gem itself; it is about where Ruby is trying to write files.

Common commands

1. Install with administrator privileges

sudo gem install mygem

2. Update RubyGems with administrator privileges

sudo gem update --system

This may work if you intentionally want to modify the system Ruby installation.

Safer long-term approach: use a Ruby version manager

With a version manager such as rbenv, you install Ruby in your own home directory.

Example workflow:

rbenv install 3.3.0
rbenv global 3.3.0
gem install bundler

Because this Ruby installation belongs to your user, gem installation usually works without sudo.

Install gems only for your user

Another approach is installing gems into a user-owned path.

gem install mygem --user-install

This installs the gem into a directory inside your home folder instead of the system directory.

You may also need to add the gem bin directory to your PATH.

Example:

export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"

The exact folder depends on your Ruby version.

Check where gems are being installed

gem env

This shows useful information such as:

• RubyGems version
• installation directory
• user installation directory
• executable directory

That helps you confirm whether RubyGems is targeting a system path or a user path.

Consider this command:

gem install colorize

Now walk through what happens.

Step 1: RubyGems starts the install

RubyGems downloads or locates the colorize gem.

Step 2: RubyGems checks the installation path

It looks at your current Ruby environment and decides where the gem should be installed.

Example target path:

/Library/Ruby/Gems/2.0.0

Step 3: The operating system checks permissions

Your user tries to write files into that directory.

Step 4: Permission is denied

Because the directory is owned by the system, the write operation fails.

Step 5: RubyGems raises an error

You see:

Gem::FilePermissionError

Example fix using a user install

gem install colorize --user-install

Now the flow changes.

1. RubyGems starts installation.
2. It chooses your user gem directory instead of the system directory.
3. Your user owns that directory.
4. The gem installs successfully.

Example fix using sudo

sudo gem install colorize

Now the flow changes in a different way.

1. The command runs with administrator privileges.
2. RubyGems can write into the protected system directory.
3. Installation succeeds, assuming no other environment issue exists.

This is why both approaches can work, but they have different tradeoffs.

Installing command-line tools

Many Ruby gems provide executable tools.

Examples:

• bundler
• jekyll
• cocoapods
• rubocop

If these tools install into a protected directory, permission errors appear immediately.

Setting up a local development machine

Developers often install Ruby and gems for:

• Rails apps
• automation scripts
• static site generators
• testing tools

A user-managed Ruby setup avoids repeated permission problems.

Continuous integration and containers

In CI or Docker images, developers usually control the full environment. They install Ruby in writable paths or as root during image setup, so permission issues are handled intentionally.

Multi-project development

Different projects may require different Ruby versions and gem versions. Version managers help isolate those environments so one project's gems do not interfere with another's.

In real projects, developers usually avoid relying on the system Ruby for application work.

Common patterns

Use Bundler for project dependencies

Instead of manually installing every gem globally:

bundle install

Bundler reads the Gemfile and installs the exact dependencies needed for that project.

Use a version manager

Teams often standardize on tools like:

• rbenv
• rvm
• asdf

This makes Ruby installations reproducible and user-owned.

Avoid sudo in day-to-day app development

Using sudo for every gem install can lead to mixed permissions and confusing environments.

Check environment before debugging

Developers often inspect:

ruby -v
which ruby
gem env
which gem

These commands help answer:

• Which Ruby is running?
• Is it the system Ruby?
• Where are gems being installed?

Keep executables on PATH

When using --user-install, developers make sure the gem executable directory is available in PATH, otherwise commands may install successfully but still appear missing.

1. Using the system Ruby for development without realizing it

Broken assumption:

gem install rails

If ruby points to the OS-provided Ruby, this may fail or create a fragile setup.

How to avoid it

Run:

which ruby
which gem

If you see system paths like /usr/bin/ruby, you are probably using the system Ruby.

2. Using sudo for everything

This works:

sudo gem install mygem

But overusing it can create file ownership problems and hide environment issues.

How to avoid it

Prefer a version manager for development work.

3. Installing with --user-install but forgetting PATH

The gem may install correctly, but its command is not found:

mygem: command not found

How to avoid it

Add the gem bin directory to your shell configuration.

Example:

export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"

4. Updating system RubyGems on a managed OS Ruby

Some operating systems expect their bundled Ruby environment to remain unchanged.

Broken approach:

gem update --system

How to avoid it

If possible, install your own Ruby instead of modifying the OS Ruby.

5. Mixing multiple Ruby environments

You may have Homebrew Ruby, system Ruby, and rbenv Ruby installed at once.

Symptoms

• ruby -v shows one version
• gem env points somewhere unexpected
• installed gems seem to disappear

How to avoid it

Check:

which ruby
which gem
ruby -v
gem env

Make sure they all refer to the same Ruby setup.

Quick rule of thumb

• Need a fast fix for a system-level install: sudo
• Need a safer personal install: --user-install
• Need a professional development setup: rbenv, rvm, or similar

Diagnose the problem

which ruby
which gem
ruby -v
gem env

Quick fixes

Install a gem with admin rights

sudo gem install mygem

Update RubyGems with admin rights

sudo gem update --system

Install only for your user

gem install mygem --user-install

Common system path that causes the error

/Library/Ruby/Gems/2.0.0

Add user gem executables to PATH

export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"

Best practice

• Avoid using system Ruby for app development
• Prefer rbenv, rvm, or asdf
• Use Bundler for project dependencies
• Use sudo only when you intentionally want to modify the system installation

Core idea

The error is usually about directory permissions, not a broken gem.

Why does gem install say I do not have write permissions?

Because RubyGems is trying to install into a system-owned directory that your user cannot modify.

Is using sudo gem install safe?

It can work, but it is best used only when you intentionally want to install into the system Ruby. For normal development, a user-owned Ruby setup is better.

What is the best way to avoid RubyGems permission errors?

Use a Ruby version manager like rbenv, rvm, or asdf so Ruby and gems are installed in your home directory.

What does --user-install do?

It installs gems into a user-specific directory instead of the system gem directory.

Why is the gem installed but the command is still not found?

The gem's executable directory is probably not in your PATH.

Should I update the system RubyGems with gem update --system?

Usually not unless you understand the consequences for your operating system's Ruby. Installing your own Ruby is often the safer choice.

How can I see where RubyGems installs packages?

Run:

gem env

This shows install directories and environment details.

Bundler

Bundler manages project-specific gem dependencies and helps avoid global gem conflicts.

rbenv

rbenv lets you install and switch between Ruby versions in a user-owned environment.

RVM

RVM is another Ruby version manager that helps isolate Rubies and gemsets.

PATH environment variable

PATH determines whether your shell can find installed gem executables.

File permissions

RubyGems permission errors are fundamentally about who can write to a directory.

System Ruby vs user-installed Ruby

Understanding this difference helps explain why one setup causes permission errors and another does not.