98

I've noticed that on rubygems.org a lot of the gems suggest you specify them by major version rather than exact version. For example...

The haml-rails gem...

gem "haml-rails", "~> 0.3.4"  # "$ bundle install" will acquire the 
                              # latest version before 1.0.

However, based on the Bundler docs it sounded to me like it would be better to nail down the exact version like this...

gem "haml-rails", "0.3.4"

So there's your haml-rails gem and all its dependencies won't drift forward. If you check out the project on a different machine a few weeks later and run $ bundle install you'll have precisely the same versions of everything you specified.

I've seen point releases break stuff, and I thought part of the whole idea of Bundler was to "Bundle.lock" all your gem versions.

But on rubygems.org they use "~>" a lot so maybe I'm missing something?

Any clarification would be very helpful to me in understanding Bundler and gem management.

1
  • I would. The less surprises the better. It only takes one time that a dependency updates without you intentionally doing it to send you down a rabbit hole for hours, or days even, to make you learn this lesson. Third-party and open-source libraries cannot be trusted to strictly follow semantic versioning (even my own libraries). Not worth the risk. May 9, 2020 at 2:06

3 Answers 3

74

This is the purpose of the Gemfile.lock file - running bundle install with a Gemfile.lock present only installs using the dependencies listed in there; it doesn't re-resolve the Gemfile. To update dependencies / update gem versions, you then have to explicitly do a bundle update, which will update your Gemfile.lock file.

If there wasn't a Gemfile.lock, deploying code to production would be a major issue because, as you mention, the dependencies and gem versions could change.

In short, you should be generally safe using the pessimistic version constraint operator (~>) as rubygems.org advises. Just be sure to re-run your tests after you do a bundle update to make sure nothing breaks.

There's a nice article by Yehuda Katz that has a little more info on Gemfile.lock.

3
  • 1
    OK, so gems stay at their established versions recorded in Gemfile.lock. So what's the purpose of adding "~>"? How is that advantageous?
    – Ethan
    Feb 13, 2012 at 19:02
  • 2
    @ethan RubyGems has a doc explaining it (see section "Preventing Version Catastrophe"). The gist of it is it only allows the last integer in the version number to increase (e.g. '~> 1.0.5' allows updating to version 1.0.9999, but never to 1.1.x). The mechanism is for allowing gems to be updated, but without introducing incompatibilities that may break things (it assumes gems are following the "Rational Versioning" policy that link outlines). Feb 13, 2012 at 19:29
  • 6
    I think the gist of what you've written is that one should keep pessimistic version constraints in one's Gemfile so one can easily upgrade to the latest version that matches both the major and minor version specified. But the Gemfile.lock file should also be used, and kept in source, so that upgrades must be done explicitly to affect any environment to which your code is deployed. Jan 30, 2016 at 16:49
23

TL;DR

Yes, use pessimistic locking (~>) and specify a semantic version down to patch (Major.minor.patch) on all your gems!

Discussion

I am surprised by the lack of clarity on this issue, even "industry experts" told me the other day that Gemfile.lock is there to maintain gem versions. Wrong!

You want to organize your Gemfile in such a manner that you can run bundle update any time without risking breaking everything. To achive this:

  1. Specify a patch-level version for all your gems with pessimistic locking. This will allow bundle update to give you fixes, but not breaking changes.

  2. Specify a ref for gems from git

The only downside to this setup is that when a sweet new minor/major version for a gem comes out, you have to bump the version up manually.

Warning scenario

Consider what happens if you do not lock your gems.
You have an unlocked gem "rails" in your gemfile and the version in Gemfile.lock is 4.1.16. You are coding along and at some point you do a bundle update. Now your Rails version jumps to 5.2.0 (provided some other gem does not prevent this) and everything breaks.
Do yourself a favor and do not allow this for any gem!

An example Gemfile

# lock that bundler
if (version = Gem::Version.new(Bundler::VERSION)) < Gem::Version.new('1.16.3')
  abort "Bundler version >= 1.16.3 is required. You are running #{version}"
end

source "http://rubygems.org"

# specify explicit ref for git repos
gem "entity_validator",
  git: "https://github.com/plataformatec/devise",
  ref: "acc45c5a44c45b252ccba65fd169a45af73ff369" # "2018-08-02"

# consider hard-lock on gems you do not want to change one bit
gem "rails", "5.1.5"

# pessimistic lock on your common gems
gem "newrelic_rpm", "~> 4.8.0"
gem "puma", "~> 3.12.0"

group :test do
  gem "simplecov", "~> 0.16.1", require: false
end

A concession
If you are confident your tests will catch bugs introduced by gem version changes, you can try pessimistic-locking gems at minor version, not patch.
This will allow the gem version to increase within the specified major version, but never into the next one.

gem "puma", "~> 3.12"
7
  • 2
    that word pessimistic is confusing here (I understand it's just semantics, but still). if you locked it onto a version with = , that's pessimistic! but ~> actually allows you to update to the newest minor version.
    – Joel Blum
    Aug 14, 2019 at 12:04
  • 6
    You wrote You want to organize your Gemfile in such a manner that you can run bundle update any time without risking breaking everything. No, this is not the goal. It sounds like you may not understand the difference between bundle update and bundle install. update updates the Gemfile.lock and changes the versions you're using. You want to be able to run bundle install any time without risking breaking everything. As it is, you're forcing the Gemfile to do what the Gemfile.lock is meant to do.
    – iconoclast
    Nov 12, 2019 at 0:20
  • 5
    And those "industry experts" are correct: Gemfile.lock does in fact maintain gem versions. Until (of course) you decide to overwrite it with bundle update (which is basically like saying bundle overwrite_my_locked_gem_versions).
    – iconoclast
    Nov 12, 2019 at 0:21
  • 1
    I don't see a difference in our definition of 'maintain'. Gemile.lock maintains (stores) the versions of the gems, but is not completely immutable—it gets mutated when you issue the bundle update command. By your definition the "industry experts" are exactly correct and this answer is misleading everyone who believes it.
    – iconoclast
    Nov 12, 2019 at 21:54
  • 3
    The way I see it (which is the reason I wrote the answer in the first place), there is a misconception that merely because there is a Gemfile.lock file that has all the exact versions, developers need not specify gem versions in Gemfile (the idea that lock 'maintains' versions). That is false. Developers 'maintain' versions by specifying them in Gemfile and running bundle update once in a while.
    – Epigene
    Nov 13, 2019 at 14:37
8

I would definitely say use the exact version numbers. You can probably always just lock it down to a major version, or never specify any version, and be okay, but if you really want that fine grained level of control and to have 100% confidence in your program when being run on other machines, use the exact version numbers.

I've been in situations where the exact version number wasn't specified, and when I or someone else did a bundle install, the project broke because it went to a newer version. This can be especially bad when deploying to production.

Bundler does lock in your gem specifications, but if you're telling it to just use a major release, then it locks that in. So is just knows "Oh the version is locked in at > 0.1" or whatever, but not "Oh the version is locked in specifically at 0.1.2.3".

6
  • 14
    If Gemfile.lock is present, then Bundler does, in fact, know which specific version to install (which is why Gemfile.lock should be stored in the repo alongside Gemfile).
    – mipadi
    Feb 13, 2012 at 18:29
  • 3
    Doing a bundle update <gem> though can end up updating way more than you thought, even if the Gemfile.lock is present, and that can be a dangerous and sticky situation.
    – MrDanA
    May 7, 2014 at 12:42
  • 1
    I agree with the recommendation from RubyGems themselves on this issue: Just use the pessimistic constraint (~>). This encourages the whole community to pile on semantic versioning, which is a good thing, and between this and the built-in stability features of Gemfile.lock your bases should be more than covered.
    – user456584
    Oct 25, 2014 at 23:15
  • 1
    @solidcell I don't believe I should have to put in the source each time I update a gem. I prefer to use as exact a version as I can, but as was mentioned, you can often just use the ~> constraint most of the time. However, I've had that give me a new, bugged version of gems before.
    – MrDanA
    Nov 20, 2014 at 13:47
  • 1
    You do not (and should not) need to use exact versions in your Gemfile. This is the purpose of Gemfile.lock. If you commit Gemfile.lock into source control, someone pulling this and doing bundle install will get the exact same versions of gems as you. Setting an exact version in the Gemfile stops you from doing bundle update gem_you_want_to_update whereas pessimistic versions (~>) or no version at all allows you to run bundle update gem_you_want_to_update and get the latest (minor) version
    – PhilT
    Dec 1, 2016 at 12:29

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.