Bundler 2.4.20 understands .ruby-version files

You can now DRY up your Ruby version declarations with Bundler’s new Gemfile syntax.

Version duplication

A minor annoyance of developing and deploying Ruby applications is having to declare and maintain a project’s Ruby version in two separate places.

Development tools like rbenv expect a .ruby-version file.
source ""
ruby "3.2.2"

gem "rails"
Deployment platforms like Heroku expect a ruby declaration in the Gemfile.

A better way

Starting with the release of Bundler 2.4.19 (and subsequently refined with a bug fix and asdf support in 2.4.20), your Gemfile can use the new ruby file: syntax.

source ""
ruby file: ".ruby-version"

gem "rails"
Bundler can now load the Ruby version from a .ruby-version file. No more duplication! Asdf’s .tool-versions file is supported as well.

How to upgrade

Taking advantage of this new Bundler feature requires a few easy steps.

1. Install the latest version of Bundler

gem install bundler

2. Update your project to use the new version

bundle commands will use the version of Bundler that is encoded into your Gemfile.lock. In order to use the new Bundler version, you’ll need to run this command to update the lock file.

bundle update --bundler

3. Edit your Gemfile

You can now edit your Gemfile to take advantage of the new syntax!

ruby file: ".ruby-version" # or ".tool-versions"


Some deployment platforms dictate the version of Bundler that can be used. For example, as of September 2023, Heroku only allows Bundler 2.3.25 (nearly a year old!), which can’t parse the new Gemfile ruby file: syntax introduced in 2.4.19.

To avoid failed deployments, check the supported Bundler version on Heroku’s Ruby support page before adopting the new syntax.


Share this? Copy link

Feedback? Email me!

Hi! 👋 I’m Matt Brictson, a software engineer in San Francisco. This site is my excuse to practice UI design, fuss over CSS, and share my interest in open source. I blog about Rails, design patterns, and other development topics.

Recent articles

View all posts →

Open source projects


Generate your next Rails app interactively! This template includes production-ready recommendations for testing, security, developer productivity, and modern frontends. Plus optional Vite support! ⚡️

Updated 7 days ago


A friendly CLI for deploying Rails apps ✨

Updated 1 month ago

More on GitHub →