How to Install a Local Gem in Ruby

By the end of this page, you will understand how Ruby gem installation works when the gem file is already on your machine. You will learn the correct gem install command for a local .gem file, what happens during installation, how dependencies affect the process, and the most common mistakes beginners make.

A Ruby gem is a packaged Ruby library or application. When you normally run gem install some_gem, RubyGems connects to a gem source such as RubyGems.org, downloads the package, and installs it.

But a .gem file is already the packaged gem itself. If you have downloaded that file manually, copied it from another machine, or built it yourself, you can install it directly from your local filesystem.

This matters because local gem installation is useful when:

• you are working offline
• you built a gem yourself and want to test it
• you received a gem file from another source
• you want to install a specific package file without re-downloading it

In Ruby, gem install can accept either:

• a gem name, such as rake
• a path to a local .gem file, such as pkg/my_gem-0.1.0.gem

So yes: if you have a .gem file stored in a folder, you can install it later by giving gem install the file path.

A local installation still follows RubyGems rules:

• the gem gets unpacked and registered in your Ruby environment
• executables may be installed if the gem provides them
• dependencies may still need to be installed separately if they are not already available

Think of a gem like a boxed product.

• gem install rails is like ordering the product from an online store by name.
• gem install ./rails-7.1.0.gem is like taking a box you already have at home and opening it for use.

The .gem file is the box. gem install is the tool that opens the box, checks its contents, and puts the files where Ruby can use them.

The basic syntax is:

gem install path/to/file.gem

Example:

gem install ./my_gem-1.0.0.gem

You can also use an absolute path:

gem install /Users/alex/downloads/my_gem-1.0.0.gem

Example workflow

Suppose you downloaded this file:

/home/user/downloads/colorize-0.8.1.gem

You can install it with:

gem install /home/user/downloads/colorize-0.8.1.gem

If the installation succeeds, RubyGems will install that gem into your current Ruby environment.

Installing a gem you built yourself

If you created a gem project and built it with:

gem build my_gem.gemspec

RubyGems may produce a file such as:

my_gem-0.1.0.gem

Then install it with:

gem install ./my_gem-0.1.0.gem

Useful option: install without documentation

Some environments skip local documentation generation:

gem install ./my_gem-0.1.0.gem --no-document

This makes installation faster and is common in development setups.

Consider this command:

gem install ./demo_gem-0.1.0.gem

What happens step by step:

1. RubyGems sees that the argument is a file path, not just a gem name.
2. It reads the local .gem package from your disk.
3. It checks the gem metadata, such as the gem name, version, and dependencies.
4. It unpacks and installs the gem into the current Ruby installation or gemset.
5. If the gem provides command-line executables, RubyGems installs those too.
6. If required dependencies are missing, RubyGems may try to resolve and install them, depending on your setup and available sources.

Small trace example

Command:

gem install ./hello_tool-1.2.0.gem --no-document

Trace:

• ./hello_tool-1.2.0.gem means: use the local file in the current directory
• --no-document means: skip generating local gem documentation
• RubyGems installs the package contents
• If the gem contains an executable such as hello_tool, that command may become available in your shell

After installation, you can often verify it with:

gem list hello_tool

Local gem installation is commonly used in these situations:

• Testing your own gem: You build a gem locally and install it to verify it works before publishing.
• Offline environments: A server or development machine may not have internet access, so you install from a copied .gem file.
• Controlled deployments: Teams may keep approved gem files internally and install only those versions.
• Debugging a package version: You may want to install a specific gem build from a file to reproduce an issue.
• CI or packaging workflows: Build artifacts may include .gem files that get installed in later steps.

Example in a build pipeline:

gem build my_tool.gemspec
gem install ./my_tool-0.4.0.gem --no-document
my_tool --help

This pattern checks that the built package can actually be installed and run.

In real Ruby projects, developers often use local gem installation in a few practical ways.

1. Testing packaged output

Developers do not only test source code. They also test the final packaged gem:

gem build my_library.gemspec
gem install ./my_library-1.0.0.gem

This catches packaging mistakes such as missing files in the gemspec.

2. Validating dependencies early

If installing the local gem fails, it often means the gemspec has incorrect or missing dependency information.

3. Using guard-style checks in scripts

Shell scripts or CI jobs often check whether the file exists before installing:

if [ -f ./pkg/my_tool-0.1.0.gem ]; then
  gem install ./pkg/my_tool-0.1.0.gem --no-document
else
  echo "Gem file not found"
fi

4. Local development with Bundler alternatives

In application development, people often prefer Bundler with a local path for active development. But when they want to verify the final distributable package, they install the actual .gem file.

5. Version-specific testing

A team may keep multiple gem files and install one exact version to reproduce behavior:

gem install ./archive/payment_sdk-2.3.1.gem

1. Passing the gem name instead of the file path

Broken example:

gem install my_gem-1.0.0.gem

This may work if the shell interprets it as a file in the current directory, but if the file is elsewhere, RubyGems will not find it.

Better:

gem install ./my_gem-1.0.0.gem

Or:

gem install /full/path/to/my_gem-1.0.0.gem

2. Running the command from the wrong directory

If the file is not in the current folder, a relative path like ./my_gem-1.0.0.gem will fail.

Check with:

ls

Then use the correct path.

3. Assuming dependencies are inside the .gem file

A .gem file packages one gem, not all its dependencies. If dependencies are missing, installation may fail or require access to gem sources.

4. Confusing gem install with Bundler

gem install installs a gem into a Ruby environment globally or per-user, depending on setup. In many app projects, dependencies are usually managed with Bundler and a Gemfile.

5. Using the wrong Ruby environment

If you use rbenv, rvm, or a system Ruby, the gem may install into a different environment than expected.

Check with:

ruby -v
gem env

6. Permission errors

Broken example:

gem install /some/path/tool.gem

If your Ruby setup uses protected system directories, you may get a permissions error.

Possible fix depends on your setup:

• use a Ruby version manager such as rbenv or rvm
• install into a user-managed Ruby
• avoid using sudo unless you understand the environment implications

Local .gem install vs Bundler path

• Local .gem install tests the packaged artifact.
• Bundler path links directly to the source code directory.

If your goal is to verify what users will actually install, testing the .gem file is often the better choice.

# Install a local gem file
gem install path/to/file.gem

# Install from current directory
gem install ./my_gem-1.0.0.gem

# Install from absolute path
gem install /full/path/to/my_gem-1.0.0.gem

# Skip documentation
gem install ./my_gem-1.0.0.gem --no-document

# Check installed gems
gem list

# Check one specific gem
gem list my_gem

# Build a gem first
gem build my_gem.gemspec

Key rules

• A local .gem file can be installed directly with gem install.
• Use the correct file path.
• The .gem file does not automatically bundle all dependencies.
• Installation happens in the current Ruby/gem environment.

Common checks

ruby -v
gem -v
gem env

Good habit

Use ./filename.gem for files in the current directory so the path is explicit.

Can I install a gem from a downloaded .gem file?

Yes. Use gem install path/to/file.gem.

Do I need an internet connection to install a local gem?

Not always. If all required dependencies are already installed, you may not need internet access. If dependencies are missing, RubyGems may still need access to fetch them.

What is the difference between installing by name and by file?

Installing by name tells RubyGems to find and download the gem. Installing by file uses a package you already have on disk.

Can I install a gem I built myself?

Yes. After running gem build, install the generated .gem file with gem install ./your_gem-x.y.z.gem.

Why does Ruby say the gem is installed but I cannot use it?

You may be using a different Ruby environment than the one where the gem was installed. Check ruby -v and gem env.

Should I use gem install or Bundler for an application?

For most Ruby applications, use Bundler and a Gemfile. Use gem install when you want to install a gem directly or test a packaged .gem file.

Can a local gem file include all its dependencies?

Usually no. A .gem file packages one gem. Dependencies are declared in metadata and are typically installed separately.

• RubyGems — The package manager that handles building, installing, and publishing gems.
• Bundler — The standard tool for managing gem dependencies in Ruby applications.
• Gemfile — Lists application dependencies for Bundler.
• gemspec — Defines a gem's metadata, files, version, and dependencies.
• Ruby version managers — Tools like rbenv and rvm help manage separate Ruby environments.
• Command line paths — Important because local gem installation depends on giving the correct file path.
• Package dependencies — Relevant because a local gem may still require other gems to be installed.