Getting Started

What is Bundler?

Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

Bundler is an exit from dependency hell, and ensures that the gems you need are present in development, staging, and production. Starting work on a project is as simple as bundle install.

What’s new in Bundler Managing dependencies

Getting Started

This guide assumes that you have Ruby installed. If you do not have Ruby installed, do that first and then check back here! Any modern distribution of Ruby comes with Bundler preinstalled by default.

Getting started with bundler is easy! Specify your dependencies in a Gemfile in your project’s root:

source 'https://rubygems.org'
gem 'nokogiri'
gem 'rack', '~> 2.2.4'
gem 'rspec'

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

Create a rubygem with Bundler

Bundler is also an easy way to create new gems. Just like you might create a standard Rails project using rails new, you can create a standard gem project with bundle gem.

Create a new gem with a README, .gemspec, Rakefile, directory structure, and all the basic boilerplate you need to describe, test, and publish a gem:

$ bundle gem my_gem
Creating gem 'my_gem'...
      create  my_gem/Gemfile
      create  my_gem/.gitignore
      create  my_gem/lib/my_gem.rb
      create  my_gem/lib/my_gem/version.rb
      create  my_gem/my_gem.gemspec
      create  my_gem/Rakefile
      create  my_gem/README.md
      create  my_gem/bin/console
      create  my_gem/bin/setup
      create  my_gem/CODE_OF_CONDUCT.md
      create  my_gem/LICENSE.txt
      create  my_gem/.travis.yml
      create  my_gem/test/test_helper.rb
      create  my_gem/test/my_gem_test.rb
Initializing git repo in ./my_gem

Learn More: bundle gem

Use Bundler with

Rails 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 or the development guide. While participating in the Bundler project, please keep the code of conduct in mind, and be inclusive and friendly towards everyone. If you have sponsorship or security questions, please contact the core team directly.

Code of Conduct #bundler on IRC Mailing list Contributing Email core team