Docs header transparent bg

In general, when working with an application managed with bundler, you should use the following workflow:

After you create your Gemfile for the first time, run

$ bundle install

Check the resulting Gemfile.lock into version control

$ git add Gemfile.lock

When checking out this repository on another development machine, run

$ bundle install

When checking out this repository on a deployment machine, run

$ bundle install --deployment

After changing the Gemfile to reflect a new or update dependency, run

$ bundle install

Make sure to check the updated Gemfile.lock into version control

$ git add Gemfile.lock

If bundle install reports a conflict, manually update the specific gems that you changed in the Gemfile

$ bundle update rails thin

If you want to update all the gems to the latest possible versions that still match the gems listed in the Gemfile, run

$ bundle update

A Thorough Bundler Workflow

Getting started with bundler is easy! Open a terminal window and run this command:

$ gem install bundler
  • When you first create a Rails application, it already comes with a Gemfile. For another kind of application (such as Sinatra), run:
$ bundle init
  • The bundle init command creates a simple Gemfile which you can edit.

Specify your dependencies in the root of your application, called the Gemfile. It looks something like this:

source ''
gem 'nokogiri'
gem 'rack', '~> 2.2.4'
gem 'rspec'

This Gemfile says a few things. First, it says that bundler should look for gems declared in the Gemfile at by default.

Learn More: Gemfiles

After declaring your first set of dependencies, you tell bundler to go get them:

$ bundle install    # `bundle` is a shortcut for `bundle install`

Bundler will connect to (and any other sources that you declared), and find a list of all of the required gems that meet the requirements you specified. Because all of the gems in your Gemfile have dependencies of their own (and some of those have their own dependencies), running bundle install on the Gemfile above will install quite a few gems.

$ bundle install
Fetching gem metadata from
Fetching version metadata from
Fetching dependency metadata from
Resolving dependencies...
Installing rake 11.3.0
Using concurrent-ruby 1.0.2
Using i18n 0.7.0
Installing minitest 5.9.1
Using thread_safe 0.3.5
Using builder 3.2.2
Using erubis 2.7.0
Using mini_portile2 2.1.0
Using rack 2.2.4
Using nio4r 1.2.1
Using websocket-extensions 0.1.2
Installing mime-types-data 3.2016.0521
Installing arel 7.1.4
Using bundler 1.13.1
Using method_source 0.8.2
Using thor 0.19.1
Using tzinfo 1.2.2
Installing nokogiri with native extensions
Using rack-test 0.6.3
Using sprockets 3.7.0
Installing websocket-driver 0.6.4 with native extensions
Installing mime-types 3.1
Using activesupport
Using loofah 2.0.3
Using mail 2.6.4
Using rails-dom-testing 2.0.1
Using globalid 0.3.7
Using activemodel
Using rails-html-sanitizer 1.0.3
Using activejob
Using activerecord
Using actionview
Using actionpack
Using actioncable
Using actionmailer
Using railties
Installing sprockets-rails 3.2.0
Using rails
Bundle complete! 1 Gemfile dependency, 38 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

If any of the needed gems are already installed, Bundler will use them. After installing any needed gems to your system, bundler writes a snapshot of all of the gems and versions that it installed to Gemfile.lock.

  • If bundle install reports a conflict between your Gemfile and Gemfile.lock, run:
$ bundle update sinatra
  • This will update just the Sinatra gem, as well as any of its dependencies.

  • To update all of the gems in your Gemfile to the latest possible versions, run:

$ bundle update
  • Whenever your Gemfile.lock changes, always check it in to version control. It keeps a history of the exact versions of all third-party code that you used to successfully run your application.

  • The git add Gemfile* command adds the Gemfile and Gemfile.lock to your repository. This ensures that other developers on your app, as well as your deployment environment, will all use the same third-party code that you are using now.

Inside your app, load up the bundled environment:

require 'bundler/setup'

# require your gems as usual
require 'nokogiri'

Learn More: Bundler.setup

Run an executable that comes with a gem in your bundle:

$ bundle exec rspec spec/models

In some cases, running executables without bundle exec may work, if the executable happens to be installed in your system and does not pull in any gems that conflict with your bundle.

However, this is unreliable and is the source of considerable pain. Even if it looks like it works, it may not work in the future or on another machine.

Finally, if you want a way to get a shortcut to gems in your bundle:

$ bundle install --binstubs
$ bin/rspec spec/models

The executables installed into bin are scoped to the bundle, and will always work.

Learn More: Executables

Edit this document on GitHub if you caught an error or noticed something was missing.