What are Gemfile, Gemfile.lock and bundle install for?
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.
Cite
Poignant 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.- Fenwick HaleStaffStaff: 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 -vtells you whether you have it. In an empty folder:bundle initThat writes a starter Gemfile. Replace its contents with:
source "https://rubygems.org" gem "rake" gem "minitest", "~> 5.0" group :development do gem "irb" endThen install:
bundle installBundler fetches every gem, plus the gems those gems depend on, and creates
Gemfile.lockbeside the Gemfile. The Gemfile reference describes each part. Thesourceline says where gems come from, eachgemline 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.1means>= 2.1and< 3.0, while~> 2.0.3means>= 2.0.3and< 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? Gemfileyou the gems you want, with loose rules yes Gemfile.lockBundler the exact version of every gem, including gems of gems yes, for an application .bundle/configBundler, via bundle configlocal 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,DEPENDENCIESandBUNDLED WITH. TheDEPENDENCIESsection is the short list you wrote. TheGEMsection carries the exact versions chosen, each in parentheses, likerake (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
bundle installafter you edit the Gemfile, or after you clone a project.bundle exec ruby app.rborbundle exec raketo run a command using exactly the locked gems.bundle update rakewhen you want one gem to move to a newer allowed version. Plainbundle updatemoves everything the Gemfile allows, so do it on purpose.bundle listto 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 installfirst, thenbundle 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 runbundle install.Adding a gem with
gem installand expecting the project to know. If it is not in the Gemfile,bundle execwill not see it, and you will getcannot load such file. Add thegemline, runbundle install.Running Ruby without bundle exec. Your script may load a different version of a gem than the lockfile says.
bundle execmakes 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
- Read the first error line, not the last. Bundler usually names the gem and the rule it could not meet.
- Run
ruby -vand compare it with anyrubyline in the Gemfile. A mismatch stops the install. The thread on installing Ruby with Homebrew and rbenv covers switching versions. - Confirm the
sourceline is spelled exactlyhttps://rubygems.org. - 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 installagain. - If the message mentions
Gemfile.lockconflicts after a git merge, restore the lockfile as above. - Paste the full error,
ruby -vandbundle -vwhen you ask for help. For how to read messages likeundefined 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 installto see your own options.
Write something first.
Give people something to work with: at least 30 words on what happened and what you tried.
That is too long. Keep it under 6,000 characters.
Write the question as the title, 15 to 140 characters, no links.
Pick a category.
Add a name (2 to 40 characters, no links).
That email address does not look right.
That was quick. Read the thread, then try again.
The form expired. Reload the page and post again.
Something went wrong with the form. Reload and try again.
Please complete the check and post again.
Limit reached for now. Try again later.
This thread is closed to new replies.
This thread no longer accepts replies.
Something went wrong with the form. Reload and try again.
Post a reply or question first (name and email), then this browser can vote, edit and accept answers.
You cannot vote on your own post.
Only the author (within 30 days) or the forum team can do that.
That email already has an account. Use your sign-in link instead.
New accounts are paused for the moment. Try again later.
That was already posted.