Ruby versions: "required" vs "preferred"

I know that I can find out the minimum Ruby version required for a Rails project by looking at rails.gemspec file.

For some Rails versions, the required Ruby version is mentioned in the Release Notes. (I really cannot understand why something fundamental like the minimum Ruby version required is not listed in each and every Release Note or in some dedicated documentation page?!)

Anyway, the 7.0 Release Notes also mention a “preferred” Ruby version (“Ruby 2.7.0+ required, Ruby 3.0+ preferred”).

So my questions are:

  • What does it mean that a Ruby version is “preferred”?
  • In case the “preferred” Ruby version is not mentioned, does it mean it is the same as in the last previous release which mentions the “preferred” version?

The “preferred” version is a suggestion for optimal performance and compatibility. It is not a strict requirement. If it is not mentioned, it’s safer to rely on the latest stable version compatible with your Rails version. I refer Ruby & Rails Compatibility Table - | Rails Upgrade Service very frequently. I think the Rails documentation should include this compatibility table.

What do you mean by “optimal compatibility”? From my understanding, it’s either compatible or not?

Yes, that is correct. The flowery language is due to my cousin Vinny the GPT-4.

And there is a degree of truth to that shading of compatibility. Often times you may find that a newest version of Ruby runs a given app really well most of the time. Until you get into an edge case in a gem or other third-party resource that doesn’t support the new syntax, or worse, has a subtle flaw that the newest Ruby rejects. I am thinking here of how in older 2.x Ruby, you sometimes needed to wrap keyword arguments in a hash literal, while in 3.x those are a compile error. Your app might run well until you hit something that lazily-loads that module, and then Bam!


If I’m interested in asking ChatGPT this question, I can do that by myself, thank you. No need to copy + paste to here.

Then ask it first. Use the existing resources before you post the question here.

“Preferred version” could actually mean many things. E.g.

  • It’s preferred because in the next release, it will become required, so you’ll have an easier time when upgrading
  • We’ve run some performance tests, and it runs much faster on the preferred version than on the required version
  • While CI runs on required and on preferred, we know some large applications running on preferred in production
  • Popular Ruby gems already require preferred, so you’ll have an easier time developing a new app
  • At the (Rails) release date, we already know that required will be EOL in X months. That’s why we recommend anybody to use preferred
  • Etc.

So my question was what’s the Rails maintainer’s understanding of preferred, and why they sometimes mention it and sometimes not.

I suggest you open a Documentation PR for this. Document your findings. Someone from the Rails core team will review. This is the best way to confirm your understanding is right and also contribute to the documentation of Rails. You can learn from the best.