Skip to content
Poignant Guide Ruby Q&A

What are Gemfile, Gemfile.lock and bundle install for?

Staff answerWritten by Fenwick Hale · Gems, Bundler and tooling0 replies

Short answer

The Gemfile is your wish list: which gems your project needs. Running bundle install picks exact versions that satisfy the list and writes them into Gemfile.lock. The lockfile is the receipt, so every machine that installs later gets the same versions. You edit the Gemfile by hand, and you let Bundler write the lockfile.

Written by Fenwick Hale · Staff: gems, Rails, tooling and debugging ·
CitePoignant Guide Ruby Q&A, "What are Gemfile, Gemfile.lock and bundle install for?", https://poignantguide.net/answers/read/what-are-gemfile-gemfilelock-and-bundle-install-for/, accessed 2026-11-21.
  1. Staff: gems, Rails, tooling and debugging ·

    A first Gemfile in two minutes

    A gem is a packaged Ruby library, and Bundler is the tool that installs the gems a project lists and keeps their versions steady. It normally comes with a Ruby install, and bundle -v tells you whether you have it. In an empty folder:

    bundle init
    

    That writes a starter Gemfile. Replace its contents with:

    source "https://rubygems.org"
    
    gem "rake"
    gem "minitest", "~> 5.0"
    
    group :development do
      gem "irb"
    end
    

    Then install:

    bundle install
    

    Bundler fetches every gem, plus the gems those gems depend on, and creates Gemfile.lock beside the Gemfile. The Gemfile reference describes each part. The source line says where gems come from, each gem line names one library, and the optional second argument limits the version.

    What the version marks mean

    The ~> mark is called the pessimistic operator. Per the reference, ~> 2.1 means >= 2.1 and < 3.0, while ~> 2.0.3 means >= 2.0.3 and < 2.1. Read it as "this version or newer, but not the next big jump". You can also use >= 1.4.2, or leave the version off and accept any.

    What lives in each file

    File Who writes it What it holds Commit it?
    Gemfile you the gems you want, with loose rules yes
    Gemfile.lock Bundler the exact version of every gem, including gems of gems yes, for an application
    .bundle/config Bundler, via bundle config local settings on your machine usually no

    The guide to how Gemfile.lock works explains why the lockfile matters: the first install resolves your Gemfile, writes the exact version of every gem, direct or transitive, and every later install reuses those versions instead of resolving again. A transitive gem is one you did not list but something you did list needs. Peek inside your lockfile and you will see more gems than you wrote, in sections named GEM, PLATFORMS, DEPENDENCIES and BUNDLED WITH. The DEPENDENCIES section is the short list you wrote. The GEM section carries the exact versions chosen, each in parentheses, like rake (13.x.y).

    Why not install gems by hand?

    You can run gem install minitest, and for one-off tools that is fine. For a project it goes wrong: your laptop has one version, your friend's has another, the server has a third, and the code behaves differently on each. The documentation for bundle install puts the promise this way: if a lockfile exists and you have not changed the Gemfile, Bundler uses the lockfile's versions instead of resolving again. Same code, everywhere.

    Daily commands

    1. bundle install after you edit the Gemfile, or after you clone a project.
    2. bundle exec ruby app.rb or bundle exec rake to run a command using exactly the locked gems.
    3. bundle update rake when you want one gem to move to a newer allowed version. Plain bundle update moves everything the Gemfile allows, so do it on purpose.
    4. bundle list to see what is installed.

    Mistakes beginners make

    Deleting Gemfile.lock when something breaks. That throws away the receipt and re-resolves everything, which can change many versions at once. Try bundle install first, then bundle update <one gem>.

    Editing Gemfile.lock by hand. Bundler regenerates it. The gems guide says never to resolve a merge conflict in it by hand: restore a clean copy (for example git checkout HEAD -- Gemfile.lock), merge the Gemfile, then run bundle install.

    Adding a gem with gem install and expecting the project to know. If it is not in the Gemfile, bundle exec will not see it, and you will get cannot load such file. Add the gem line, run bundle install.

    Running Ruby without bundle exec. Your script may load a different version of a gem than the lockfile says. bundle exec makes Ruby use the locked gems.

    Running Bundler from the wrong folder. Bundler looks for the Gemfile in the current folder, so run commands from the project root.

    Check this in order when bundle install fails

    1. Read the first error line, not the last. Bundler usually names the gem and the rule it could not meet.
    2. Run ruby -v and compare it with any ruby line in the Gemfile. A mismatch stops the install. The thread on installing Ruby with Homebrew and rbenv covers switching versions.
    3. Confirm the source line is spelled exactly https://rubygems.org.
    4. If the message says a gem needs to build native extensions, read the next few lines for a missing tool. Install it, then run bundle install again.
    5. If the message mentions Gemfile.lock conflicts after a git merge, restore the lockfile as above.
    6. Paste the full error, ruby -v and bundle -v when you ask for help. For how to read messages like undefined method, see this explanation of nil errors.

    For a sense of where this sits, the parent guide's page about IRB is a gentle first stop before you start collecting gems.

    Checked on 12 November 2026. The Bundler pages above were generated from Bundler 4.x; if your installed version is older, run bundle help install to see your own options.

    2
    ReplyLink

Plain text or simple Markdown. Links are nofollow. Your email is never shown.

Poignant Guide Ruby Q&A. Questions and answers on learning Ruby and programming: syntax, blocks, objects, gems, Rails, debugging and reading the Poignant Guide.