Creating Your First Gem

Share this article

You see gems everywhere in the Ruby world. They are the backbone of just about every Ruby app out there. I’ll admit that I was a bit intimidated the first time I tried to create a gem, but I soon found out that it’s dead simple. In this blog series I will start by covering the basics of creating a gem from scratch, and then move on to more advanced topics including gem generation tools and Rails Engines. First things first, for all you Ruby newbies out there: What is a gem? Simply put, it is packaged Ruby code. At the bare minimum, a gem includes a Ruby file and a gemspec. The gemspec (gem specification) describes the gem and is used by the RubyGems package manager to install the gem.


The RubyGems package manager can download and install gems to your system and allows you to use the gems in other Ruby programs. Ruby 1.9 comes with RubyGems installed by default. If you are using a version prior to Ruby 1.9, you can download RubyGems here. To use RubyGems in a pre Ruby 1.9 app, you will need add this line in your app:
require 'rubygems'
Ruby 1.9 does not need this line, since RubyGems is included in the language.

Gem Specification

As I mentioned before, the gem specification describes the gem. Let’s take a look at a basic gemspec file: do |s| = %q{my_gem}
  s.version = "0.0.1" = %q{2011-09-29}
  s.summary = %q{my_gem is an awesome gem}
  s.files = [
  s.require_paths = ["lib"]
The gemspec is a fairly simple file that describes various aspects of your gem. I am only listing the required attributes and the files in the example gemspec above. The first 4 attributes are self-explanatory. The “files” attribute lists all of the files that are included in the gem. The “require_paths” attribute specifies the directory that contains the Ruby files that should be loaded with the gem. For a complete list of the attributes that can be used in the gemspec, go here. That is about as academic as I can get without falling asleep, so let’s cut to the chase and get to the good stuff.

Creating a Gem From Scratch

1. Create the basic file structure of the gem:

Fire up your shell and create the directories that will be needed in your gem:
$ mkdir awesome_gem
$ cd awesome_gem
$ mkdir lib
That’s it! You need a root directory for your gem and a lib directory to hold your Ruby file.

2. Create the gemspec

We will use the template from the previous section for our gemspec file. Create a file named “awesome_gem.gemspec” in your gem’s root directory. Then add some code to make a valid gemspec: do |s| = %q{awesome_gem}
  s.version = "0.0.0" = %q{2011-09-29}
  s.summary = %q{awesome_gem is the best}
  s.files = [
  s.require_paths = ["lib"]
This file contains the standard required attributes for a gemspec and shows that we have one file inside the “lib” directory. The file “awesome_gem.rb” in the lib directory is the main file that will be used to hold the Ruby code in this gem.

3. Add some code

To keep things simple, we will use only one Ruby file in this gem: /lib/awesome_gem.rb You will see this type of structure in most gems you come across. The root file inside “lib” will usually match the name of the gem. In this case “awesome_gem” and “/lib/awesome_gem.rb”. Go ahead and create this file and add the following code to it:
module AwesomeGem
  class WhoIs
    def self.awesome?
      puts "YOU ARE AWESOME!!"
This is not exactly code that will change the world, but at least the “awesome?” method will boost your self-esteem! This gem will allow you to use the class method “awesome?” from WhoIs in other Ruby programs. As I mentioned in the first section, RubyGems will install the gem in your app and give you access to the classes in your gem.

4. Generate the gem file

Now that you have some awesome code, you will want to create a gem so you can use this awesome code in another Ruby program. Rubygems has a command line interface that allows you to create a gem. Fire off this command inside the root directory of your gem:
$ gem build awesome_gem.gemspec
This command will build the gem and output a gem file that will include the version number in the file name. Since the gemspec contains a version attribute with a value of “0.0.0”, the gem file will be named awesome_gem-0.0.0. You should see the following output and some warnings about missing attributes:
Successfully built RubyGem
  Name: awesome_gem
  Version: 0.0.0
  File: awesome_gem-0.0.0.gem
But you don’t care about warnings, because you are living on the edge and you are “awesome”. So you decide to move on and install this gem on your system. Notice that the gem file was created in your current directory.

5. Install the gem

Now that you have a gem file, you can use RubyGems to install the gem on your computer. Typically you install gems from external sources, but you are not restricted to that. If you have access to the gem file, you can install it locally by specifying the location of the gem file that will be installed. Here is the command to install awesome_gem.gem locally:
$ gem install awesome_gem.gemspec
You should get the following output:
Successfully installed awesome_gem-0.0.0
1 gem installed
Installing ri documentation for awesome_gem-0.0.0...
Installing RDoc documentation for awesome_gem-0.0.0...
Ah Yeah! You just created a gem! The gem is now installed on your system and ready to be used in another Ruby program.

6. Add The Gem to Another Ruby Program

Create a new Ruby file that will be used to test out our gem. Let’s call it “be_awesome.rb”. You can create this file anywhere on your system and then add the following code so we can use the “awesome?” class method from our gem. You just have to require ‘awesome_gem’ and RubyGems will be able to find the gem and make the class available to your program. Then you just call the class method from your namespaced class. Here is the code:
require 'awesome_gem'

Now you can run the Ruby program and test out your newly created gem and see how awesome you are. Fire it up via the command line:
$ ruby be_awesome.rb
You should see the following output in your shell:
Congratulations, you just used your new gem in a program! I don’t think I would put that one on github and brag about it, but hey.. you still learned how to create a gem from scratch and use it in another program. Now you can move on to bigger and better things.


While this tutorial was fairly simple and only covered the basics of creating a gem, I think it is still very important information for those that are new to gem development. The basics will give you a good foundation for more advanced topics. I use Jeweler to create gems and while it is a great productivity tool, I feel that diving into generation tools before you create a gem from scratch can be harmful. You need to understand how to build a gem in the simplest form before you can understand the what is behind the code that a generation tool like Jeweler can give you. While I recommend building a gem from scratch when you are first learning gem development, I see absolutely no reason why you should not use a generator after you understand the basics. Generators are a huge time-saver since they give you a good skeleton to start with. The next blog post in this series will cover more advanced topics related to gem development, as well as a primer to using generation tools to give you a starting point for your gems. Later installments will explain how you develop gems for Ruby on Rails. Stay tuned….

Frequently Asked Questions (FAQs) about Creating Your First Gem

What are the prerequisites for creating a Ruby gem?

Before you start creating a Ruby gem, you need to have a good understanding of Ruby programming language. You should also have Ruby and RubyGems installed on your computer. RubyGems is a package manager for the Ruby programming language that provides a standard format for distributing Ruby programs and libraries. It is advisable to have a basic understanding of how to use the command line as most of the work will be done using command line tools.

How do I structure my Ruby gem?

A Ruby gem has a specific directory structure. At the root of the directory, you should have a gemspec file which describes the gem, its version, and other metadata. You should also have a lib directory where the code for your gem lives. If your gem includes executable files, they should be placed in the bin directory. You can also include a test directory for your test files and a doc directory for documentation.

How do I create a gemspec file?

A gemspec file is a Ruby file that contains metadata about your gem. It includes information like the name of the gem, version, authors, email, summary, description, and homepage. It also includes a list of files included in the gem and any runtime or development dependencies. You can create a gemspec file using any text editor and save it with a .gemspec extension.

How do I build my Ruby gem?

Once you have created your gemspec file and written your code, you can build your gem using the gem build command followed by the name of your gemspec file. This will create a .gem file which is a packaged version of your gem that can be installed on any machine that has RubyGems installed.

How do I install my Ruby gem?

After building your gem, you can install it using the gem install command followed by the name of your .gem file. This will install the gem on your machine and make it available for use in your Ruby programs.

How do I publish my Ruby gem?

To publish your gem, you need to create an account on Once you have an account, you can publish your gem using the gem push command followed by the name of your .gem file. This will upload your gem to and make it available for others to install.

How do I update my Ruby gem?

To update your gem, you need to change the version number in your gemspec file and then rebuild your gem using the gem build command. After that, you can publish the updated version of your gem using the gem push command.

How do I add dependencies to my Ruby gem?

If your gem depends on other gems, you can specify these dependencies in your gemspec file. You need to add each dependency to the add_dependency method in your gemspec file, specifying the name of the gem and the version requirement.

How do I test my Ruby gem?

It’s important to test your gem to ensure it works as expected. You can write tests using a testing framework like RSpec or MiniTest and run them using the appropriate command. You should include tests for all the main functionality of your gem.

How do I document my Ruby gem?

Good documentation is crucial for any gem. You can include a README file in your gem’s root directory that provides an overview of your gem and instructions on how to use it. You can also include more detailed documentation in the doc directory.

John McAlileyJohn McAliley
View Author

My name is John McAliley. I try to develop good software and try to help others by sharing my experiences and answering questions. For the last few years I have been blogging about Ruby and Rails at Currently, I am co-owner of, an online coupon database and, which provides interactive geographic heatmaps for longitude/latitude data. I used to be a Java developer for several large corporations and I am glad that is behind me. I am a fan of agile methods. And yes, I am a recovering cowboy coder.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week