In a Ruby project, Gemfile.lock records the exact version of every gem Bundler resolved, direct or transitive, plus a SHA-256 checksum of each packaged gem. Commit it for applications, install from it in CI and production, and treat changes to it as reviewable code changes.
What is inside Gemfile.lock?
The RubyGems guide describes it as the output of dependency resolution. The first bundle install resolves your Gemfile and writes the exact version of every gem into the lockfile. Every later install reuses those versions instead of resolving again, so teammates and deploys run the same code. Bundler maintains the file, and you never edit it by hand.
The main sections:
- GEM: one block per gem server, with the remote and every resolved gem at its exact version. Transitive dependencies are locked as precisely as direct ones. In the guide's example, a Gemfile asking for one gem from the server produced six entries.
- GIT and PATH: gems from a repository get a pinned commit under revision. A path source records only the location, and its contents are read from that directory on every install.
- PLATFORMS: the platforms the resolution covers.
- DEPENDENCIES: your direct dependencies. A trailing exclamation mark marks a gem from a non-default source.
- CHECKSUMS: the SHA-256 digest of each packaged gem file.
- BUNDLED WITH: the Bundler version that wrote the file.
Why do the checksums matter?
The guide says Bundler verifies every gem against its checksum during installation, so a gem tampered with after the lockfile was written fails to install. That protects deploys against a compromised gem source. Gems from git and path sources have no packaged file, so they carry no checksum. Bundler writes the section into new lockfiles by default, and the guide points to a documented route for adding it to older ones.
This is integrity after first resolution. It does not tell you whether the version you locked was safe on the day you locked it.
Should you commit it?
For an application, always. The guide says an uncommitted lockfile silently turns every install back into a fresh resolution. For a gem, the lockfile is not part of the package, and applications that depend on your gem ignore any lockfile it ships.
Two housekeeping notes from the same guide. Run the normalize-platforms command before committing, so macOS lockfiles do not disagree on a Darwin version number. And never resolve a merge conflict in Gemfile.lock by hand: restore one side from git, merge the Gemfile, and let bundle install re-lock.
How should deploys use it?
The deployment guide says to add Gemfile and Gemfile.lock to source control and ignore the machine-specific .bundle directory. It describes the deployment flag as encapsulating best practices, and says it requires an up-to-date Gemfile.lock. In production, that means a deploy fails when the Gemfile and lockfile disagree, rather than quietly resolving something new.
What does a cooldown add?
New releases are the riskiest. The RubyGems guide on cooldown notes that most malicious gem releases are detected and yanked within days of publication, and describes a setting that excludes versions newer than a chosen number of days from resolution. It can be set in Bundler config, an environment variable or per source in the Gemfile, with a command-line flag taking precedence. A trusted private gem server can be exempted with a value of zero.
Constructed example. A team sets a seven-day cooldown for public gems and zero for its private server. A hijacked maintainer account pushes a bad release on Monday. The team's routine update on Wednesday cannot select it, and by Friday it has been yanked.
What to do
- Commit Gemfile.lock for every application and never edit it by hand.
- Run the normalize-platforms command before each commit.
- Install with the deployment option in CI and production so mismatches fail loudly.
- Review lockfile diffs in pull requests like any dependency change, including transitive additions.
- Confirm the CHECKSUMS section exists in older lockfiles and add it if missing.
- Set a cooldown for public gems, with an exemption for your own server.
- Prefer released versions over git branches, and pin git sources to a revision.
- Scan the lockfile for known vulnerabilities on every pull request.
Safeguard can read Ruby lockfiles to inventory dependencies and report vulnerable gems, and the free scan at gold.safeguard.sh/scan covers 100 dependencies.
Quick check
Does a lockfile stop malicious gems?
Not by itself. It keeps installs repeatable and verifies integrity against recorded checksums. A bad version locked on day one stays locked until you update, so scan and review.
Should a gem commit its own Gemfile.lock?
It is a development tradeoff. Applications that depend on your gem ignore your lockfile, so it protects only your own repository.
Sources
- RubyGems Guides: How Gemfile.lock works
- RubyGems Guides: How to deploy bundled applications
- RubyGems Guides: How to delay new gem versions with cooldown
Last reviewed: 18 October 2026.
