Ruby Gems & Bundler Cheat Sheet
Covers RubyGems CLI commands, Gemfile syntax, Bundler workflows, and semantic version constraint operators for managing dependencies.
gem CLI
Managing individual gems directly with RubyGems.
gem install rails # Install a gem globallygem list # List installed gemsgem uninstall rails # Remove a gemgem search rails # Search RubyGems.orggem build mygem.gemspec # Build a gem packagegem push mygem-1.0.0.gem # Publish to RubyGems.org
Gemfile Syntax
Declaring dependencies and environment-specific groups.
# Gemfilesource "https://rubygems.org"ruby "3.2.2"gem "rails", "~> 7.1.0"gem "pg", ">= 1.4"gem "puma"group :development, :test do gem "rspec-rails" gem "pry"endgroup :production do gem "redis"endgem "rack-cors", git: "https://github.com/cyu/rack-cors.git", branch: "main"
Bundler CLI
Installing and running gems with locked versions.
bundle install # Install gems from Gemfile, write Gemfile.lockbundle update # Update all gems to latest allowed versionsbundle update rails # Update just one gembundle exec rspec # Run a command using bundled gem versionsbundle exec rails serverbundle check # Verify all gems are installedbundle add sidekiq # Add a gem to Gemfile and install it
Version Constraints
How Bundler interprets common version operators.
- ~> 7.1.0- Pessimistic constraint: allows patch updates only, equivalent to >= 7.1.0 and < 7.2.0
- ~> 7.1- Allows minor and patch updates, equivalent to >= 7.1 and < 8.0
- >= 1.4- Any version 1.4 or newer, including major version bumps
- Gemfile.lock- Records the exact resolved versions; commit it to ensure identical installs across environments
- bundle exec- Runs a command in the context of the Gemfile's locked gem versions, avoiding conflicts with system gems
- group blocks- Scope gems to environments (development/test/production) so bundle install --without can skip them
bundle config
Overriding install behavior per-machine without touching the Gemfile.
bundle config set --local path 'vendor/bundle' # Install gems into project dirbundle config set --local without 'development test' # Skip groups on installbundle config set --global jobs 4 # Parallel install workersbundle config mirror.https://rubygems.org https://gem-mirror.internalbundle config list # Show all active settingsBUNDLE_GEMFILE=Gemfile.ci bundle install # Point at an alternate Gemfile
Binstubs & Bundler.require
Generating fast executable wrappers and autoloading gems at boot.
bundle binstubs rspec-core --path bin # Creates bin/rspec, skips bundle exec overheadbin/rspec spec/models/post_spec.rb# config/boot.rb (Rails-style autoload of Gemfile groups)# require "bundler/setup"# Bundler.require(:default, Rails.env)bundle exec ruby -e 'puts Gem.loaded_specs["rails"].version'
Bundler Internals & Diagnostics
Lesser-used commands for inspecting and repairing dependency state.
- bundle lock --local- Recomputes Gemfile.lock using only already-downloaded gems, no network access
- bundle outdated- Lists gems with newer versions available, respecting the constraints in the Gemfile
- bundle cache / package- Vendors .gem files into vendor/cache so installs work offline or without RubyGems.org
- bundle doctor- Diagnoses common issues like broken native extension links or invalid load paths
- PLATFORMS section- Gemfile.lock records resolved platforms (e.g. x86_64-linux, arm64-darwin) for native gem builds
- bundle platform- Shows your current Ruby/platform and flags gems with unmet platform requirements
- DEPENDENCIES vs GEM sections- Gemfile.lock separates direct Gemfile entries from the full resolved dependency graph
Scoped & Private Sources
Pulling individual gems from a private registry or git ref without changing the global source.
# Gemfilesource "https://rubygems.org"source "https://gems.mycompany.internal" do gem "internal-auth"endgem "my-fork", git: "https://github.com/me/my-fork.git", ref: "a1b2c3d"gem "local-tool", path: "../local-tool"# Credentials for a private source, stored outside the Gemfile# bundle config set https://gems.mycompany.internal myuser:mytoken
Commit Gemfile.lock for applications (not for gems you're publishing) so every environment, including CI and production, resolves the exact same dependency versions.