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

I am interested in

Getting Started

Getting started with bundler is easy
$ gem install bundler

Specify your dependencies in a Gemfile in your project's root
source 'https://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 Rails

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. 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

To find out whether a newer version of a gem is available without updating yet:
$ bundle outdated nokogiri

Check for newer pre-release versions: bundle outdated nokogiri --pre

Or leave off the gem name to check for newer versions of all gems: $ bundle outdated

Learn More: bundle outdated

Deploying Your Application

On production servers, you can enable deployment mode:
$ bundle install --deployment
Do not use this flag on development machines. The --deployment flag turns on defaults that are appropriate for a deployment environment. Gems are installed to vendor/bundle and the Gemfile.lock must be checked in and up to date before Bundler is run.
Learn More: deploying

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'
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 => 'https://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
Create a code file along with the installed gems that can load dependencies without Bundler
$ bundle install --standalone
Learn More: bundle install
Edit this document on GitHub if you caught an error or noticed something was missing.