What does 'require: false' in Gemfile mean?

This means install the gem, but do not call require when you start Bundler. So you will need to manually call

require "whenever"

if you want to use the library.

If you were to do

gem "whenever", require: "whereever"

then bundler would download the gem named whenever, but would call

require "whereever"

This is often used if the name of library to require is different than the name of the gem.

You use :require => false when you want the gem to be installed but not "required".

So in the example you gave: gem 'whenever', :require => false when someone runs bundle install the whenever gem would be installed as with gem install whenever. Whenever is used to create cron jobs by running a rake task but isn't usually used from within the rails (or other framework if not rails) application.

So you can use :require => false for anything that you need to run from the command line but don't need within your code.

require: false tells Bundler.require not to require that specific gem: the gem must be required explicitly via require 'gem'.

This option does not affect:

• bundle install: the gem will get installed regardless

• the require search path setup by bundler.

  Bundler adds things to the path when you do either of:

  • Bundle.setup
  • which is called by require bundler/setup
  • which is called by bundle exec

Example

Gemfile

source 'https://rubygems.org'
gem 'haml'
gem 'faker', require: false

main.rb

# Fail because we haven't done Bundler.require yet.
# bundle exec does not automatically require anything for us,
# it only puts them in the require path.
begin Haml; rescue NameError; else raise; end
begin Faker; rescue NameError; else raise; end

# The Bundler object is automatically required on `bundle exec`.
Bundler.require

Haml
# Not required because of the require: false on the Gemfile.
# THIS is what `require: false` does.
begin Faker; rescue NameError; else raise; end

# Faker is in the path because Bundle.setup is done automatically
# when we use `bundle exec`. This is not affected by `require: false`.
require 'faker'
Faker

Then the following won't raise exceptions:

bundle install --path=.bundle
bundle exec ruby main.rb

On GitHub for you to play with it.

Rails usage

As explained in the initialization tutorial, the default Rails template runs on startup:

• config/boot.rb
• config/application.rb

config/boot.rb contains:

ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])

which does the require 'bundler/setup' and sets up the require path.

config/application.rb does:

Bundler.require(:default, Rails.env)

which actually requires the gems.