Bundler: The best way to manage a Ruby application's gems

What is Bundler?

Bundler maintains a consistent environment for ruby applications. It tracks an application's code and the rubygems it needs to run, so that an application will always have the exact gems (and versions) that it needs to run.

We designed bundler to make it easy to share your code across a number of development, staging and production machines. Of course, you know how to share your own application or gem: stick it on GitHub and clone it where you need it. Bundler makes it easy to make sure that your application has the dependencies it needs to start up and run without errors.

Learn More: Why Bundler exists

Getting Started

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

$ 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

The second 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 '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.

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

Use Bundler with

Rails 3 Rails 2.3 Sinatra RubyGems RubyMotion

Get involved

Bundler has a lot of contributors and users, and they all talk to each other quite a bit. If you have questions, try the IRC channel or mailing list. If you're interested in contributing to the project (no programming skills needed), read the contributing guide. If you have sponsorship or security questions, please contact the core team directly.

#bundler on IRC Mailing list Contributing Core team