Configuring bundler using bundle config

Bundler helps in managing gem dependencies of ruby projects. You can specify which gems and versions you need, bundler will install them and load them at runtime. Bundler ensures that gems you need are present in the environment you need.

Bundle configurations

Bundler gets its configurations from local application (app/.bundle/config), environment variables and user’s home directory (~/.bundle/config) in the order of priority.

To list all bundler configurations for the current bundle, run bundle config without any parameters. You will also get the location where the value is set.

$ bundle config
Settings are listed in order of priority. The top value will be used.

You might see different result based on configuration of bundler on your machine.

To get value for the specific configuration setting, run bundle config with name.

$ bundle config disable_multisource
Settings for `disable_multisource` in order of priority. The top value will be used
You have not configured a value for `disable_multistore`

Setting Configuration

To set the value of the configuration setting, use bundle config with name and value. Configuration will be stored in ~/.bundle/config.

$ bundle config build.pg --with-pg-config=/opt/local/lib/postgresql91/bin/pg_config

$ bundle config
Settings are listed in order of priority. The top value will be used.
build.pg
Set for the current user (/Users/username/.bundle/config): "--with-pg-config=/opt/local/lib/postgresql91/bin/pg_config"

If any config already has a value, it will be overwritten directly and user will be warned.

$ bundle config build.pg --with-pg-config=/usr/pgsql-9.1/bin/pg_config
You are replacing the current global value of build.pg, which is currently "--with-pg-config=/opt/local/lib/postgresql91/bin/pg_config"

Application level configuration

By default setting configuration value will set it for all projects on the machine. You can set configurations specific to local application with --local option. This will store value in app/.bundle/config.

$ bundle config --local auto_install false
You are replacing the current local value of auto_install, which is currently nil

$ bundle config auto_install
Settings for `auto_install` in order of priority. The top value will be used
Set for your local app (/Users/username/Documents/Workspace/app-name/.bundle/config): "false"
Set for the current user (/Users/username/.bundle/config): "true"

You can run bundle config with --global. This will set values at global level i.e. across all applications on the machine. It will be similar to running bundle config without any options.

Deleting configuration

You can delete configuration with --delete option.

$ bundle config --delete auto_install
$ bundle config
Settings are listed in order of priority. The top value will be used.
disable_multisource
Set for the current user (/Users/username/.bundle/config): "true"

build.pg
Set for the current user (/Users/username/.bundle/config): "--with-pg-config=/usr/pgsql-9.1/bin/pg_config"

This is not compatible with --local and --global. This will delete configuration from local and global resources.

Build Options

You can pass the flags required for installing particular gem to bundler with bundle config.

Many El Capitan users face an issue while installing eventmachine gem. The issue can be resolved by providing path to OpenSSL include directory while installing eventmachine.

$ gem install eventmachine -v '1.0.8' -- --with-cppflags=-I/usr/local/opt/openssl/include

As location of configuration will vary from machine to machine, we can set this with bundle config.

$ bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include

Now bundler will pick this configuration while installing eventmachine gem.

Configuration keys

Various configuration keys are available with bundler. These keys are available in two forms. You can specify them in canonical form with bundle config or set them in environment variable form. Following are canonical forms and their usage. Corresponding environment variables are specified in bracket.

auto_install

Setting auto_install config will enable automatic installing of gems instead of raising an error. This applies to show, binstubs, outdated, exec, open, console, license, clean commands.

Example, When you try to run bundle show for the gem which is not yet installed you will get an error.

$ bundle show pg
Could not find gem 'pg'.

You can set auto_install to remove this error and install gem.

$ bundle config auto_install true

$ bundle show pg
# Gem will get installed
/Users/username/.rvm/gems/ruby-2.2.2@gemset-auto/gems/pg-0.17.1

path (BUNDLE_PATH)

You can specify location to install your gems. Default path is $GEM_HOME for development and vendor/bundle when --deployment is used.

$ bundle config path NEW_PATH
$ bundle install
# Gems will get installed
#
#
Bundle complete! 4 Gemfile dependencies, 35 gems now installed.
Bundled gems are installed into NEW_PATH.

frozen (BUNDLE_FROZEN)

You can freeze changes to your Gemfile.

$ bundle config frozen true

If frozen is set and you try to run bundle install with changed Gemfile, you will get following warning.

You are trying to install in deployment mode after changing
your Gemfile. Run `bundle install` elsewhere and add the
updated Gemfile.lock to version control.

If this is a development machine, remove the /Users/username/Documents/Workspace/app-name/Gemfile freeze
by running `bundle install --no-deployment`.

You have added to the Gemfile:
* minitest-reporters

without (BUNDLE_WITHOUT)

You can skip installing groups of gems with bundle install. Specify : separated group names whose gems bundler should not install.

$ bundle config --local without development:test

$ bundle install
# This will install gems skipping development and test group gems.

bin (BUNDLE_BIN)

You can set the directory to install executables from gems in the bundle.

$ bundle config bin NEW_PATH

$ bundle install
# This will install executables in NEW_PATH

gemfile (BUNDLE_GEMFILE)

You can set the file which bundler should use as theGemfile. By default, bundler will use Gemfile. The location of this file also sets the root of the project, which is used to resolve relative paths in the Gemfile.

$ bundle config gemfile Gemfile-rails4

$ bundle install
# This will install gems from Gemfile-rails4 file.

ssl_ca_cert (BUNDLE_SSL_CA_CERT)

This specifies path to a designated CA certificate file or folder containing multiple certificates for trusted CAs in PEM format. You can specify your own https sources in Gemfile with corresponding certificates specified via bundle config.

$ bundle config ssl_ca_cert NEW_CERTIFICATE_PATH

ssl_client_cert (BUNDLE_SSL_CLIENT_CERT)

This specifies path to a designated file containing a X.509 client certificate and key in PEM format.

$ bundle config ssl_client_cert NEW_CERTIFICATE_PATH

cache_path (BUNDLE_CACHE_PATH)

You can set the path to place cached gems while running bundle package.

$ bundle config cache_path vendor/new-cache-path

$ bundle package
Using colorize 0.7.7
Using pg 0.17.1
Using bundler 1.11.2
Updating files in vendor/new-cache-path
  * colorize-0.7.7.gem
  * pg-0.17.1.gem
Bundle complete! 2 Gemfile dependencies, 3 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
Updating files in vendor/new-cache-path

disable_multisource (BUNDLE_DISABLE_MULTISOURCE)

When set, Gemfiles containing multiple sources will produce an error instead of a warning.

With Gemfile,

source 'https://rubygems.org'
source 'http://gems.github.com'

ruby '2.2.2'

When you try to run bundle install, you will get warning.

$ bundle install
Warning: this Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source. To upgrade this warning to an error, run `bundle config disable_multisource true`.

$ bundle config --local disable_multisource true

$ bundle install
[!] There was an error parsing `Gemfile`: Warning: this Gemfile contains multiple primary sources. Each source after the first must include a block to indicate which gems should come from that source. To downgrade this error to a warning, run `bundle config --delete disable_multisource`. Bundler cannot continue.

 #  from /Users/username/Documents/Workspace//Gemfile:2
 #  -------------------------------------------
 #  source 'https://rubygems.org'
 >  source 'http://gems.github.com'
 #
 #  -------------------------------------------

To ignore all bundle config on the machine and run bundle install, set BUNDLE_IGNORE_CONFIG environment variable.