Matthew Lindfied Seager

Matthew Lindfied Seager

Matching Bundler Version with Heroku

Bundler is a very helpful tool for managing third party dependencies in Ruby.

Bundler takes a “Gemfile” where you specify which gems you want to use (and potentially which version). When you run bundle (or bundle install) it reads the Gemfile and automagically figures out dependencies, sub-dependencies, sub-sub-dependencies (you get the idea) and then tries to find mutually compatible versions of each of them. Once it’s done that it downloads them all, installs them and then records which versions it chose in a Gemfile.lock. You then commit your Gemfile and Gemfile.lock to version control to make sure your collaborators (and your deployed application!) are all using the same trusted versions.

Bundler is itself a gem so you do need to install it before you can use it to install (and manage) all your other gems. Assuming you already have ruby installed it’s as simple as:
gem install bundler


Recently, I was deploying an application to Heroku and I noticed a warning from the remote system. It’s only a warning but wherever possible I like to treat warnings as errors, otherwise they tend to build up and accumulate and hide real problems in the noise. Anyway the warning was:

Warning: the running version of Bundler (1.15.2) is older than the version that created the lockfile (1.17.1). We suggest you upgrade to the latest version of Bundler by running gem install bundler

On a local machine that message (and the following two lines I snipped) is quite helpful but not so much when it’s coming from a server I can’t control. Thankfully, Heroku have documented all this very thoroughly. You should definitely read their documentation but the short version is that they only support a limited number of “carefully curated” bundler versions.

The best way around such warnings is to match your local version of Bundler to Heroku’s carefully curated version(s). That page above links to another page with the currently supported versions:
https://devcenter.heroku.com/articles/ruby-support#libraries

As of today that’s version 2.0.1 for Gemfile.locks bundled with 2.x and 1.15.2 for everything else.


I ended up upgrading to Bundler 2.0.1 but I could just as easily have reverted to 1.15.2.

Below are some instructions on how to manage which version(s) of Bundler you have installed and how to massage your environment to use a particular version of Bundler.

# To check which version(s) of bundler you currently have installed:
$ gem list | grep bundler
bundler (1.17.1)

# To install an older version
$ gem install bundler -v 1.15.2
Fetching: bundler-1.15.2.gem (100%)
...
1 gem installed

# To install currently supported 2.x version (currently 2.0.1)
$ gem install bundler -v 2.0.1
Fetching: bundler-2.0.1.gem (100%)
...
1 gem installed

# Check again:
$ gem list | grep bundler
bundler (2.0.1, 1.17.1, 1.15.2)

# Bundle with the latest installed version (now 2.0.1)
$ bundle install

# Try to bundle with an older version (may break if your Gemfile.lock was built with 2.x)
$ bundle _1.15.2_ install
Traceback...
Could not find 'bundler' (2.0.1) required by your Gemfile.lock (Gem::GemNotFoundException)

# Actually bundle with an older version
$ rm Gemfile.lock
$ bundle _1.15.2_ install