Bundler: The best way to manage Ruby applications

Bundler manages an application's dependencies through its entire life across many machines systematically and repeatably.

I am interested in

Reporting a Bug

Understanding Bundler

Gemfile Manual

CLI Manual

Getting Started

Getting started with bundler is easy

$ gem install bundler --pre

If you're on an old version of Rubygems (before 1.3.6)

$ gem update --system

Specify your dependencies in a Gemfile in your project's root

source "http://rubygems.org"
gem "nokogiri"
gem "rack", "~>1.1"
gem "rspec", :require => "spec"

Learn More: Gemfiles

Install all of the required gems from your specified sources

$ bundle install
$ git add Gemfile Gemfile.lock

Learn More: bundle install

Make sure to add Gemfile.lock to your repository. This will ensure that other developers on your app, as well as your deployment environment, use exactly the same third-party code as you just installed.

Inside your app, load up the bundled environment

require "rubygems"
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.

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

Using Bundler with Frameworks

Bundler works out of the box with Rails 3. Once you understand the basics of using bundler, you know everything you need to know. Using Bundler with Rails 3

Bundler works with Rails 2.3 with a small change to boot.rb and adding a preinitializer.rb. Using Bundler with Rails 2.3

Checking Out an Application With a Gemfile for Development

Install the required gems

$ bundle install

Learn More: bundle install

If your system stores its gems in a root-owned location (this is the default for Mac OSX), bundler will ask you for your password, so it can install the gems there.

Updating Your Dependencies

Make a change to your Gemfile

# change
gem "nokogiri", "1.4.2"
# to
gem "nokogiri", "1.4.3"

Install the new gems

$ bundle install

After making a change to your Gemfile, the next bundle install will try to update the gems in your snapshot (Gemfile.lock) without forcing an update to any of the other gems in your Gemfile.

This will usually work for simple dependencies, like nokogiri or sqlite3-ruby. On the other hand, updating Rails will usually require an update to some other component, because of the amount of dependencies it has.

If bundler reports a conflict, tell bundler to explicitly update the gem, but none of the other top-level dependencies (the ones in your Gemfile)

$ bundle update rails

Learn More: bundle update

In some rare cases, bundler will be unable to update the dependency without updating the top-level dependencies as well. In this case, tell bundler to update all dependencies

$ bundle update

Deploying Your Application

Install the required gems for your application into your application's directory

$ bundle install --deployment

The --deployment flag turns on defaults that are appropriate for a deployment environment. For instance, gems are installed to vendor/bundle by default and your Gemfile.lock must be up to date.

Use the built-in Capistrano recipe to quickly and easily deploy your application

require "bundler/capistrano"

This recipe will symlink your vendor/bundle to shared/vendor_bundle, speeding up deployments by sharing downloaded gems across deployments, but not between applications.

Digging Further

Store all of the required gems in your application. All future installs will get gems from this cache, bypassing rubygems.org

$ bundle package

Learn More: bundle package

Put dependencies in a group, so they can be ignored at install time or required together in your application

group :development do
  gem "wirble"
end

Learn more: Groups

Use a gem that is stored in git and has a .gemspec at its root. Bundler will make the executables available to bundle exec and compile C extensions

gem "nokogiri", :git =>
  "git://github.com/tenderlove/nokogiri.git"

Learn more: Git

Use a gem that you are actively developing on your file system

gem "nokogiri", :path => "~/Code/nokogiri"

Install gems to an alternate location. By default, bundler installs your gems to the system location

$ bundle install --path vendor

When installing to a path, bundler completely isolates your gems from the system, guaranteeing you a clear set of dependencies.

Learn More: bundle install