The CHECKSUMS section in Gemfile.lock stores a checksum for each gem. During install, Bundler verifies each downloaded gem against it. A gem that was tampered with after the lock file was created fails to install. New lockfiles get the section automatically; existing ones need a command.
What the RubyGems documentation says
The security page states that Bundler records a CHECKSUMS section in newly generated lockfiles and verifies each gem against its checksum during installation. Existing lockfiles are not rewritten automatically. The bundle config reference lists a setting named lockfile_checksums, which controls whether new lockfiles include the section and which defaults to true. It describes the purpose as protecting from compromised gem sources.
What it protects against
| Scenario | Does the checksum help? |
|---|---|
| A gem file is replaced on a mirror or proxy after you locked | Yes, the install fails |
| A gem host serves different bytes for the same version | Yes |
| A new malicious version is published and you update to it | No, you recorded its checksum |
| A maintainer account is taken over and a bad release is pushed before you lock | No |
It proves that the bytes you install match the bytes you locked. It does not prove the bytes were safe in the first place. Treat it as integrity, not trust.
Steps to adopt it
- Check whether your Gemfile.lock already has a CHECKSUMS section near the bottom.
- If not, add checksums with the lock command shown below.
- Review the diff. It should only add checksum lines.
- Commit the change on its own so it is easy to audit.
- Leave checksum validation switched on in CI.
bundle lock --add-checksums
git diff Gemfile.lock
A setting to watch
The config reference includes disable_checksum_validation, which allows installing gems even if they do not match the checksum provided by RubyGems. Search your CI and Docker files for it. If it is set, find out why. Turning off validation removes the protection this section exists to give.
Pair it with other controls
Checksums catch tampering after locking. To reduce the chance of locking something bad, combine them with a review of Gemfile.lock diffs, an advisory scan on the locked set, and optionally a delay on brand new releases, as in our guide to the RubyGems cooldown.
Try it yourself
Click through it at your own pace, or open it full screen. Notice that every locked package has an exact version you can verify.
Where Safeguard fits
Safeguard's reachability analysis helps separate advisories your code can reach from those it cannot. You can try a free scan on your own lock file.
Quick check
Do old Gemfile.lock files get checksums automatically?
No. The RubyGems security page says existing lockfiles are not rewritten, and gives a command to add them.
Do checksums detect a malicious new release?
No. They show that what you install matches what you locked, not that it is safe.
Sources
Last reviewed: 19 October 2026.
