Share this post!

Ruby Gems, Gemfile & Bundler (The Ultimate Guide)

A Ruby gem packages together Ruby code in a way that is easy to share with others.

Gems solve mostly two problems:

  • A common format for sharing libraries & tools in Ruby
  • A way to describe dependencies so they are installed automatically with the gem

Thanks to Ruby gems we have a rich ecosystem of helpful libraries just one gem install away.

What are some examples of Ruby gems?

  • Rails, and all of its components (ActiveRecord, ActiveSupport, etc.) are distributed as gems
  • Pry, the powerful alternative to irb
  • Nokogiri, a popular XML & HTML parser

Most gems are pure Ruby code, sometimes requiring other gems to work.

A few gems include a Ruby C extension for improved performance. The extension is built automatically for you when you install the gem, in some cases you may need to manually install additional software that is not managed by RubyGems.


Let’s learn more about gems by building your own & looking at the files that make a gem.

How to Build a Ruby Gem

You can prepare the files for a new gem by running bundle gem <name>.

For example:

bundle gem awesome_gem

A Gem is composed of the following structure:

├── awesome_gem.gemspec
├── bin
│   ├── console
│   └── setup
├── Gemfile
├── lib
│   ├── awesome_gem
│   │   └── version.rb
│   └── awesome_gem.rb
├── Rakefile
└── test
    ├── awesome_gem_test.rb
    └── test_helper.rb

This .gemspec file is where you’ll find all the information about the gem.

It includes:

  • Gem name
  • Gem summary (short description)
  • Author name
  • Dependency list
  • A list of files to include in the gem
  • Optional: Author’s email address, project URL (homepage), executables, c extensions, long description.

The gem version itself is defined as a constant in lib/<gem_name>/version.rb.

Here’s an example gemspec: do |spec|          = "awesome_gem"
  spec.version       = AwesomeGem::VERSION
  spec.authors       = ["Jesus Castello"]
  spec.summary       = "Example gem for article about Ruby gems"

  spec.files         = Dir['**/**'].grep_v(/.gem$/)

  spec.require_paths = ["lib"]

  spec.add_development_dependency "bundler", "~> 1.16"
  spec.add_development_dependency "rake", "~> 10.0"
  spec.add_development_dependency "minitest", "~> 5.0"

The require_paths array is where Ruby will look for your gem files when you require them. This allows you to put your code under lib/<gem_name>/ & then require it with require "<gem_name>/<file_name>".

For example:

A file named lib/awesome_gem/parser.rb would be required as require "awesome_gem/parser" from anywhere inside the gem.

You will have most of your requires in lib/<gem_name>.rb (the only file at the root of /lib).

That’s the file that gets loaded when you require the gem!


The add_development_dependency lines define gems that you’re going to use during development.

These are gems like minitest, RSpec, or pry.

While add_dependency defines gems that you use as part of your code.

Once you’ve changed the summary & description from the default values… you’ll able to load an irb session with your gem using the bin/console program that bundle gem creates for you.


$ bin/console

irb(main):003:0> AwesomeGem
=> AwesomeGem
irb(main):005:0> AwesomeGem::VERSION
=> "0.1.0"

Then you can package the gem using gem build <name>.gemspec & publish it to using gem push.

What Is Bundler?

While learning about Ruby gems you may also read about Bundler.

But what is Bundler exactly?

Bundler is a tool for dependency management.

Didn’t RubyGems already handle this?

Well, it does… but only for the gems themselves.

Your regular Ruby application isn’t built as a gem, so it doesn’t get this feature.

That’s why Bundler exists!

Understanding Gemfiles

Have you seen those Gemfile files?

That’s where you write what gems you want to use for your Ruby application.

These gems will be loaded for you without having to require them.

A Gemfile looks like this:

ruby '2.5.0'

gem 'rails', '~> 5.2.1'
gem 'sqlite3'
gem 'puma', '~> 3.11'
gem 'bootsnap', '>= 1.1.0', require: false

Bundler (and RubyGems since version 2.0) can read this file & install the requested versions of these gems.

This is what you should see when running the bundle command:

Using turbolinks-source 5.1.0
Using turbolinks 5.1.1
Using uglifier 4.1.18
Using web-console 3.6.2

Bundle complete! 18 Gemfile dependencies, 78 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.


What are these symbols (like ~>) used when declaring the versions for every gem?

These allow you to request a range of versions.

You can say things like, “I want the version to be equal or greater than 1.2, but less than 2.0”.

Which would look like this:

gem 'puma', '~> 1.2'

The ~> is a shortcut for this range:

gem 'puma', '>= 1.2', '< 2.0'

In the case of ~> 5.2.1, it means exactly this:

'>= 5.2.1', '< 5.3'

The more specific the version number is the more restricted the version range will be.

Gemfile Options & Gemfile.lock

You have a few extra options when requiring a gem inside a Gemfile.

For example:

You may want to pull a gem directly from GitHub.

This is helpful when you need to use the latest version of the project, even if hasn't been released on yet.

Here's an example:

gem "rails", git: ""

You can pass a branch option to use the code from a branch that isn't master.

Like this:

gem "awesome_print", git: "", branch: "v2"

Another option you may see is require: false.

What does that do?

It tells Bundler to not auto-require the gem for you. This means that you'll have to require the gem in your code when you need it.

This is used for gems that are limited in scope.

For example:

Gems that you use in a specific rake task, but you don't use in your Rails controllers & models. The benefit is that you save memory in your app code because you only load that gem when you need it.

You can also group gems by environment.

That means you can have gems that are only installed & loaded in development (like capybara & pry).

Finally, bundler creates a Gemfile.lock.

What's the difference?

A Gemfile.lock is auto-generated & it says exactly what versions of every gem were installed.

Bundler will install these versions so when you deploy this application to production, or share your project with other developers, everyone will be working with an identical set of gems.

Useful Gem & Bundler Commands

Command Description
gem list List all your installed gems. Accepts an argument for filtering gems by name (example: gem list active)
gem which <name> Gives you the path where a gem is installed.
gem search <name> Search gems from configured sources (default: Takes a regular expression (example: gem search "\Aawesome_").
gem env Displays information about your gem environment (version, paths, configuration).
gem install <name> -v <version> Allows you to install a specific gem version (example: gem install sinatra -v 2.0.0).
bundle viz Generates a visualization of the dependency graph for your current project.
bundle show Shows info about a particular gem installed via bundler. Must be inside a folder with a Gemfile.
bundle outdated Displays a list of outdated gems in the current project. Can use the --groups option to group them.
bundle console Runs an irb session with the gems from the current project's Gemfile.


You've learned about RubyGems, the package system for Ruby. You've also learned how a gem is structured, what is a Gemfile, Bundler & the difference between the Gemfile & the Gemfile.lock.

I hope you found this useful!

Please share this article, subscribe to the newsletter if you haven't yet (6000+ Ruby developers!) & check out my Ruby book.

Thanks for reading & have a great day 🙂