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

Source: https://poignantguide.net/answers/read/what-are-gemfile-gemfilelock-and-bundle-install-for/
Site: Poignant Guide Ruby Q&A, category Gems, Bundler and tooling
Published: 2026-11-19. Updated: 2026-11-19. Replies: 0.

## Question by Fenwick Hale (staff), 2026-11-19

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.

## 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:

```bash
bundle init
```

That writes a starter Gemfile. Replace its contents with:

```ruby
source "https://rubygems.org"

gem "rake"
gem "minitest", "~> 5.0"

group :development do
  gem "irb"
end
```

Then install:

```bash
bundle install
```

Bundler fetches every gem, plus the gems those gems depend on, and creates `Gemfile.lock` beside the Gemfile. The [Gemfile reference](https://guides.rubygems.org/gemfile/) 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](https://guides.rubygems.org/gemfile-lock/) 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](https://guides.rubygems.org/command-reference/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](/answers/read/how-do-i-install-ruby-on-a-mac-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](/answers/read/what-does-undefined-method-for-nilnilclass-mean-and-how-do-i-fix-it/).

For a sense of where this sits, the [parent guide's page about IRB](https://poignantguide.net/ruby/expansion-pak-1.html) 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.

---
Cite as: 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.
