Read the .ruby-version into your Gemfile

Previously I recommended using a loose version ruby version constraint in your Gemfile. This is still a valuable technique, but here’s another useful variation that’s works well for most of us, most of the time.

The UK’s friendliest, Ruby & Rails event.
Thursday 19th June, 2025.
Includes ice cream

Hat tip to Emma for the this one-liner.

Ruby version managers (such as chruby) ensure an application uses a specific version of Ruby by looking for a .ruby-version file in the root directory of each app.

The file specifies the required version of Ruby for the application and the manager automatically switches the environment to use the specified version.

The version can also be specified in your Gemfile using bundler, which is more often used to define the version of Ruby to use in a deployed application.

Instead of…

…specifying your exact ruby version in two places and potentially generating conflicts:

# Gemfile
ruby "3.0.0"

# .ruby-version
3.1.2

This results in an error, as bundler checks the current version of Ruby specified in the Gemfile.

Your Ruby version is 3.0.0, but your Gemfile specified 2.7.2

Prior to rubygems version 2.4.19 use…

…the fact that the Gemfile is simply another Ruby file:

# Gemfile
ruby File.read(".ruby-version").strip

# .ruby-version
3.1.2

Actually use…

…the file argument.

# Gemfile
ruby file: ".ruby-version"

# .ruby-version
3.1.2

This enhancement was released in August 2023 here’s the addition in PR #6876 and there’s been a couple of bug fixes too.

You might need to run the following commands to get onto the latest rubygems and bundler for your application.

gem update --system
bundle update --bundler

Why?

This means that when you upgrade Ruby you only need to update in one place: the .ruby-version file.

Most of us, most of the time, are happy to specify a version of Ruby for all environments and this is a cool micro-improvement that reminds us that the Gemfile is just another ruby script!

Why not?

There are still services where the availability of new Ruby versions are delayed so the prevous loose ruby version technique might be a better fit for your project.

Also

If you’re using ASDF for multiple tool management (rather than solely a ruby version manager), the file: argument supports .tool-versions files too.

That functionality was added in version 2.4.20 in September 2023 via PR #6898

Last updated on February 7th, 2024