How to Publish a Gem to RubyGems.org

Updated

To publish a gem to RubyGems.org, you need a RubyGems.org account, a gem packaged with a valid gemspec, and the gem push command. After pushing, the gem becomes available for search and installation by anyone. The steps below cover account setup, packaging, publishing, and what to check afterward.

Prerequisites

Before publishing, make sure you have:

  • A RubyGems.org account — sign up at rubygems.org. Publishing requires authentication, so an account is mandatory.
  • Ruby and RubyGems installed locally — the gem command ships with Ruby.
  • A gem project with a .gemspec file describing the gem's name, version, authors, and files.
  • A unique gem name — names are global on RubyGems.org, so check availability first.

Step 1: Prepare the gemspec

Your .gemspec defines what gets published. At minimum it should specify:

Gem::Specification.new do |spec|
  spec.name          = "your_gem_name"
  spec.version       = "0.1.0"
  spec.authors       = ["Your Name"]
  spec.email         = ["[email protected]"]
  spec.summary       = "A short summary"
  spec.description   = "A longer description"
  spec.homepage      = "https://example.com"
  spec.license       = "MIT"
  spec.files         = Dir["lib/**/*.rb"]
  spec.require_paths = ["lib"]
end

The name and version fields are what RubyGems.org uses to identify your release. Each new push must use a version number that hasn't been published before.

Step 2: Build the gem

From your project directory, run:

gem build your_gem_name.gemspec

Expected result: a .gem file appears in the current directory, named like your_gem_name-0.1.0.gem. If the build fails, the error usually points to a missing required field or an invalid version format.

Step 3: Authenticate with RubyGems.org

The first time you push, RubyGems prompts for your credentials and stores an API key locally:

gem push your_gem_name-0.1.0.gem

You'll be asked for your RubyGems.org email and password. On success, the key is saved to ~/.gem/credentials, so later pushes don't require re-entering it.

Step 4: Push the gem

Run the same command to publish:

gem push your_gem_name-0.1.0.gem

Expected result: output confirming the gem was pushed, and the gem page becomes live at https://rubygems.org/gems/your_gem_name. It will also appear in RubyGems.org search results.

Step 5: Verify the release

After pushing:

  • Visit https://rubygems.org/gems/your_gem_name to confirm the version, description, and metadata.
  • Test installation in a clean environment: gem install your_gem_name.
  • Check that the gem shows up in search on the RubyGems.org homepage.

Publishing updates

To release a new version, bump spec.version in the gemspec, rebuild, and push again:

gem build your_gem_name.gemspec
gem push your_gem_name-0.2.0.gem

RubyGems.org keeps every published version, so users can install specific ones with gem install your_gem_name -v 0.1.0.

Common issues

Problem Likely cause
"Name has already been taken" The gem name is registered to someone else — choose a new name.
"Version already exists" You're pushing a version number already published — bump the version.
Push rejected / authentication error Credentials are wrong or the API key is missing — re-run gem push and re-enter them.
Gem installs but files are missing spec.files doesn't include the needed paths — fix the gemspec and republish with a new version.

What happens after publishing

Once live, your gem is discoverable through RubyGems.org search and installable via gem install. RubyGems.org is a community-run service maintained by Ruby Central's Open Source Program and the RubyGems team; the site notes that the Supporter Program and donations help fund its maintenance and operations. As a publisher, you remain responsible for updating the gem, responding to issues, and releasing new versions as needed.