/commands/bundler/bundle-add-gem
bundle add gemname: add a gem to the Gemfile and install it
- tool
- Bundler
- versions
- Bundler 2.x
- os
- any
bundle add rack appends gem "rack", "~> X.Y" to the Gemfile (with a pessimistic constraint on the newest version), updates Gemfile.lock and installs the gem, all in one step. Add --version for a specific constraint, --group for development or test gems, and --skip-install to only edit the files. It is the Bundler equivalent of npm install pkg or cargo add; editing the Gemfile by hand and running bundle install gives the same result.
Usage
bundle add rack # newest version, saved as "~> X.Y"
bundle add rack --version "~> 3.1" # explicit constraint
bundle add rack --version "3.1.8" # exact version
bundle add rspec-rails --group "development, test"
bundle add my_gem --git https://github.com/acme/my_gem --branch main
bundle add my_gem --path ../my_gem # local gem for development
bundle add rack --skip-install # only edit Gemfile and Gemfile.lock
bundle remove rack # take it out againRun it in the folder with the Gemfile; elsewhere Bundler stops with Could not locate Gemfile. In a new project, create the file first with bundle init.
Options
| Option | What it does |
|---|---|
| --version, -v | Version constraint to write, for example "~> 3.1" or ">= 2.0, < 4" |
| --group, -g | Put the gem in one or more Gemfile groups |
| --require, -r | Value for require: (false to not auto-require the gem) |
| --source, -s | Gem server to use for this gem |
| --git / --branch / --ref | Take the gem from a git repository |
| --github | Shortcut for a GitHub repository |
| --path | Use a gem from a local folder |
| --skip-install | Do not install, only edit the Gemfile and lock file |
| --strict / --optimistic | Write an exact (=) or a >= constraint instead of ~> |
Pitfalls
- Pessimistic constraint. The default
~> 3.1allows 3.x from 3.1 but not 4.0. Updates within that range needbundle update rack; a new major needs a constraint change. - Install location. Gems are installed where Bundler is configured to put them; with
bundle config set --local path vendor/bundlethey go into the project. See bundle config path. - Running the gem's command. After adding a gem that ships an executable, run it with bundle exec so the locked version is used.
- Ruby version. A gem that requires a newer Ruby than yours fails to resolve; the error names the
required_ruby_version. Pick an older gem version with--version.
How to confirm it worked
The Gemfile contains the new gem line, Gemfile.lock lists the resolved version, and bundle info rack prints the installed version and path. bundle exec ruby -e 'require "rack"; puts Rack.release' loads it through the bundle.
FAQ
What is the difference between bundle add and gem install?
gem install puts a gem into the Ruby installation without recording it anywhere. bundle add writes it to the Gemfile, resolves it into Gemfile.lock and installs it, so every machine using the project gets the same gem and version.
How do I add a gem only for development and test?
Use --group, for example bundle add rspec-rails --group "development, test". Bundler writes the gem inside the matching group block in the Gemfile.
How do I add a gem without installing it yet?
Pass --skip-install. Bundler edits the Gemfile and resolves the lock file, and you run bundle install later, for example inside a Docker build.