How to install a gem

if you know the name of a gem, and you want to install it, what has to actually happen before you can `require` and start using the gem? a walk through how gems work, how gem servers work, and how rubygems organizes files on disk so that ruby can find and use them.

Transcript

1. André Arko @indirect // March 24, 2026 // SF Ruby Meetup How to install a gem it's harder than it sounds, really
2. rv.dev gem.coop
3. how do you install a gem?
4. how about what’s in a gem?
5. what about how require works?
6. How does a name 
 become a .gem URL?
7. › curl -s https: //gem.coop/info/rails | tail -n 1 8.1.3 actioncable:= 8.1.3,actionmailbox:= 8.1.3,actionmailer:= 8.1.3,actionpack:= 8.1.3,actiontext:= 8.1.3,actionview:= 8.1.3,activejob:= 8.1.3,activemodel:= 8.1.3,activerecord:= 8.1.3,activestorage:= 8.1.3,activesupport:= 8.1.3,bundler:>= 1.15.0,railties:= 8.1.3| checksum:6d017ba5348c98fc909753a8169b21d44de14d2a0b92 d140d1a966834c3c9cd3,ruby:>= 3.2.0,rubygems:>= 1.8.11
8. › curl -s https: //gem.coop/info/rails | tail -n 1 8.1.3 actioncable:= 8.1.3,actionmailbox:= 8.1.3,actionmailer:= 8.1.3,actionpack:= 8.1.3,actiontext:= 8.1.3,actionview:= 8.1.3,activejob:= 8.1.3,activemodel:= 8.1.3,activerecord:= 8.1.3,activestorage:= 8.1.3,activesupport:= 8.1.3,bundler:>= 1.15.0,railties:= 8.1.3| checksum:6d017ba5348c98fc909753a8169b21d44de14d2a0b92 d140d1a966834c3c9cd3,ruby:>= 3.2.0,rubygems:>= 1.8.11
9. checksum:6d017ba5348c98fc909753a8169b21d44de14d2a0 b92d140d1a966834c3c9cd3 › curl -sO https: //gem.coop/gems/rails-8.1.3.gem › sha256sum rails-8.1.3.gem 6d017ba5348c98fc909753a8169b21d44de14d2a0b92d140d1 a966834c3c9cd3 rails-8.1.3.gem
10. what exactly is in a gem?
11. › tar xfvz railties-8.1.3.gem x metadata.gz x data.tar.gz x checksums.yaml.gz
12. › gzcat checksums.yaml.gz --- SHA256: metadata.gz: 8326ab6cc8e325055394ebd19c41d895e9ebd48e4752ec90d5c4675935516e6e data.tar.gz: 4152d8f55ae639d899f1cb6c54e1e93bb158bb76026b253482c5ae0343ac5aec SHA512: metadata.gz: f6aa3390b6b1699255f1dbc6c6f24c6d9c18d3bfa48f10b6d720595384b4d1bb 26f92232adb7011d3b1e7e977ca775cd253a12a135fe83eaa21e10dd0f14f779 data.tar.gz: a001cebc5b97f627336a3e8d394c4ecac4a5d2b9e62c82de3b484470a58deac7 c8ff0a8e8b497843386b1639c9cbfdfabee2cc7b2d483469e00a0b01da6bd41d
13. › gzcat metadata.gz --- !ruby/object:Gem::Specification name: railties version: !ruby/object:Gem::Version version: 8.1.3 platform: ruby bindir: exe executables: - rails require_paths: - lib authors: - David Heinemeier Hansson summary: Tools for creating, working with, and running Rails applications. description: 'Rails internals: application bootup, plugins, generators, and rake tasks.' email: david@loudthinking.com homepage: https: //rubyonrails.org licenses: - MIT metadata: bug_tracker_uri: https: //github.com/rails/rails/issues changelog_uri: https: //github.com/rails/rails/blob/v8.1.3/railties/CHANGELOG.md documentation_uri: https: //api.rubyonrails.org/v8.1.3/ mailing_list_uri: https: //discuss.rubyonrails.org/c/rubyonrails-talk source_code_uri: https: //github.com/rails/rails/tree/v8.1.3/railties rubygems_mfa_required: 'true' rubygems_version: 4.0.6 specification_version: 4 files: - CHANGELOG.md - MIT-LICENSE - RDOC_MAIN.md - README.rdoc - exe/rails - lib/minitest/rails_plugin.rb - lib/rails.rb [ ...]
14. › gzcat metadata.gz --- !ruby/object:Gem::Specification name: railties version: !ruby/object:Gem::Version version: 8.1.3 platform: ruby bindir: exe executables: - rails require_paths: - lib
15. what gets unpacked, where?
16. › mkdir railties-8.1.3 › tar xfvz data.tar.gz -C railties-8.1.3 x CHANGELOG.md x MIT-LICENSE x RDOC_MAIN.md x README.rdoc x exe/rails x lib/minitest/rails_plugin.rb x lib/rails.rb [ ...]
17. › ruby -e 'puts Gem.dir' /Users/andre/.gem/ruby/4.0.0 › ls ~/.gem/ruby/4.0.0 | xargs -L1 echo bin build_info cache doc extensions gems plugins specifications
18. mv railties-8.1.3.gem ~/.gem/ruby/4.0.0/cache/
19. › gunzip metadata.gz › ruby -ryaml -e 'puts YAML.unsafe_load_file("metadata").to_ruby' > ~/.gem/ruby/4.0.0/specifications/ railties-8.1.3.specification
20. › mv railties-8.1.3 ~/.gem/ruby/4.0.0/gems/ › ls ~/.gem/ruby/4.0.0/gems/railties-8.1.3 CHANGELOG.md exe lib MIT-LICENSE RDOC_MAIN.md README.rdoc
21. › cat <<EOF > ~/.gem/ruby/4.0.0/bin/rails #!/usr/bin/env ruby require "rubygems" Gem.activate_and_load_bin_path("railties", "rails") EOF › chmod +x ~/.gem/ruby/4.0.0/bin/rails
22. › ~/.gem/ruby/4.0.0/bin/rails Usage: rails COMMAND [options] You must specify a command: new Create a new Rails application. "rails new my_app" creates a new application called MyApp in "./my_app"
23. how does require find a gem?
24. › mkdir lib › echo 'puts "this is some ruby"' > lib/my-file.rb › ruby -Ilib -e 'puts $LOAD_PATH.first; \ require "my-file"' /Users/andre/lib this is some ruby
25. how do we require 'rails'?
26. require "rails" # becomes require "~/.gem/ruby/4.0.0/gems/railties-8.1.3/ lib/rails.rb" # and works!
27. ! gems installed !
28. rv.dev
 
 spinel.coop