Versions, Releases and Compatibility

A Ruby version is MAJOR.MINOR.TEENY, for example 4.0.7: major 4, minor 0, teeny (the patch release) 7. Three points about it are easy to get wrong.

Ruby 4.0 is the release after 3.4. The 3.5 name was used for the development series: the releases list shows 3.5.0-preview1 (2025-04-18), then 4.0.0-preview2, so the series shipped as 4.0. The number change did not come with a flag-day break. The 4.0.0 announcement lists two headline features, both labelled experimental, plus a set of smaller improvements:

The timeline shows the headline changes of each release since 3.0. The 4.1 entry comes from the preview announcement and can still change before the final release.

Source: NEWS for Ruby 4.0.0, NEWS for Ruby 3.4.0 and Ruby 4.0.0 Released

A version check says what the interpreter is called; a feature check says what it can do. Feature checks keep working on other implementations, on development builds and on a release that backports a method, and they read better: the test names the capability instead of the number it appeared in. Use respond_to? for a method on an object, method_defined? for an instance method of a class, and defined? for a constant or other construct.

Output:

Three things the table shows. Set and Pathname are present without a require in 4.0 because they are core classes now; on 3.2 and later Set was autoloaded and on older versions it needed require "set", so a library that still runs on 3.x keeps the require (it is harmless). Ractor.yield is gone in 4.0, so respond_to? is the right probe for the old Ractor API. And Ractor::Port is a constant, so defined? is the right probe for the new one.

When a version check is the only option, such as a behaviour change with no new method, compare with Gem::Version, never with strings, and compare RUBY_VERSION (the language) rather than RUBY_ENGINE_VERSION, because an alternative implementation reports the language version it implements in RUBY_VERSION and its own release number in RUBY_ENGINE_VERSION.

Source: Object#respond_to?, Module#method_defined?, Miscellaneous syntax: defined? and Ractor::Port

.ruby-version is a plain text file with a version number on one line, a convention that version managers such as rbenv, chruby and RVM read, and that Bundler can read through the Gemfile (below). Version managers are community tools that ruby-lang.org only lists; the installation options are on Getting Started. One difference is worth knowing because it surprises people: mise reads .ruby-version only when idiomatic version files are enabled for Ruby (mise settings add idiomatic_version_file_enable_tools ruby); the setting is off by default, so in a directory with .ruby-version set to 4.0.7 a plain mise current can still report the system Ruby. Its own file, mise.toml, always works.

Bundler’s ruby method states the Ruby a project needs. It accepts a literal version, several requirements that must all hold, a version file, and an engine for projects that run on another implementation. The three Gemfiles below are alternatives: each is a complete file of its own.

Source: Gemfile reference: ruby

The first form reads .ruby-version (and, in the Bundler documentation, .tool-versions) so that the Gemfile and the version manager can never disagree. The third pins JRuby: the first argument is the language version, engine_version the implementation’s own; the numbers shown are an illustration (it was not run here, as JRuby is not installed), and a real Gemfile uses the two values that the engine prints for RUBY_VERSION and RUBY_ENGINE_VERSION. On CRuby the engine version must equal the Ruby version, and a patch level in the ruby line has been meaningless since Ruby 2.1.

When the running Ruby does not match, Bundler stops before running anything. With .ruby-version changed to 3.3.12, a command run through bundle exec fails like this (the path prefix is shortened):

With the file set to 4.0.7 the same command runs, and bundle install records the version in Gemfile.lock under a RUBY VERSION heading next to BUNDLED WITH 4.0.20, so the lock file also tells a reader which Ruby it was resolved with. Ruby 4.0 ships RubyGems and Bundler 4.0.x (the 4.0 series share one version number); the latest Bundler supports every Ruby that has not reached end of life, and Bundler 4.0 itself requires Ruby 3.2 or newer. See RubyGems and Bundler.

Source: Gemfile reference: ruby, Bundler compatibility with Ruby and mise: idiomatic version files

A gem declares the Rubies it supports with required_ruby_version, as the shelf gemspec does:

RubyGems checks the requirement at install time. Building a copy of this gem with ">= 5.0" and installing it on 4.0.7 fails with:

Choose the requirement for the oldest Ruby the test suite really runs on. A lower bound (>= 4.0) is the normal case. An upper bound ("< 5") is rarely wise: it blocks users on a future Ruby that would have worked, and the only way to lift it is a new release of your gem. ~> 4.0 is the same as ">= 4.0", "< 5". See Creating and Publishing Gems, and Rake.

Source: Specification Reference: required_ruby_version and Make your own gem

The -W option sets the global $-W (and the related $VERBOSE), which decides how talkative the interpreter is:

The options guide and ruby -h describe -w as a synonym for -W1, but the interpreter sets $-W to 2 and $VERBOSE to true for it, as the table (checked by running each option on 4.0.7) shows; treat -w as -W2. A script can also change the variable while running ($VERBOSE = nil silences everything, which is almost never a good idea in a library).

Since Ruby 2.7.2 deprecation warnings are no longer shown by default, which is why code that is about to break often runs without a sound. Warnings carry a category, and each category has its own switch. Warning.categories (added in 3.4) lists the categories of the running Ruby:

The switches are the same everywhere: on the command line with -W:category and -W:no-category, in the environment with RUBYOPT, and in code with Warning[category] and Warning[category] = flag. -w and -W2 also turn :deprecated on.

Source: Ruby command-line options: -W and -w

This is the chilled string migration step of 3.4. A string literal in a file without a frozen_string_literal magic comment is not frozen, but mutating it emits a deprecation warning when :deprecated is on; "a".frozen? still answers false. Frozen string literals are not the default in 4.0, and the proposal to make them the default (Feature 20205) is still open, waiting on a migration plan. To get frozen literals today, add frozen_string_literal: true to each file, or pass --enable-frozen-string-literal; --disable-frozen-string-literal switches the chilled warning off. The effect on strings is described on Strings and Literals. Mutating the result of Symbol#to_s produces the same kind of warning (also from 3.4): warning: string returned by :sym.to_s will be frozen in the future.

Other warnings that a deprecation run can show in 4.0:

Source: NEWS for Ruby 4.0.0

A practical habit follows: run the test suite once per upgrade with RUBYOPT=-W:deprecated (or -w) and read the warnings before moving to the next Ruby, because a warning in version N is the error in version N+1 or N+2. -W:no-experimental silences the experimental category, for example when a project uses Ractors on purpose.

Warning[] and Warning[]= read and set a category; Warning.categories lists them. Kernel#warn writes a warning and takes two keywords: uplevel: prefixes the message with the file and line of a caller (the usual way to point at the code that called a deprecated method), and category: makes the message conditional on that category being enabled. An unknown category raises ArgumentError from Warning[].

Output:

Source: module Warning and Kernel#warn

The first assignment turns :deprecated on, so the ISBN-10 message is printed; after switching it off the same call is silent, while a warn without a category is never filtered. uplevel: 1 reports the line of the caller of old_api (line 24), not the line of the warn inside it.

All warnings, from the interpreter and from Kernel#warn, end in the singleton method Warning.warn, which writes to $stderr. Customising it is the supported way to filter, collect or redirect warnings: extend Warning with a module that defines warn and call super for the default behaviour. Never redefine the instance method Warning#warn, which removes the way back to the default. The category: keyword is passed to it since Ruby 3.0.

Output:

The warn with category :performance is dropped before it reaches Warning.warn because that category is off, while the interpreter’s own message about reassigning a constant arrives as two ordinary messages (the second names the earlier definition). A test suite can use the same hook to fail on any warning that comes from the project’s own files.

Source: module Warning, Kernel#warn, Ruby command-line options: -W and -w and NEWS for Ruby 3.4.0

Many libraries that older tutorials call "the standard library" are no longer loaded from it. There are three kinds:

Libraries move from the first kind to the second over time. The releases so far:

On the command line the difference is invisible: ruby -e 'require "logger"' works because the bundled gem is installed. Under Bundler without a Gemfile entry, the same require fails, with a helpful warning first:

gem list shows the difference: json (default: 2.18.0) is a default gem, while logger (1.7.0) and benchmark (0.5.0) are ordinary entries. The fix is a line in the Gemfile or the gemspec’s add_dependency. See Standard Library Tour and RubyGems and Bundler.

Source: NEWS for Ruby 4.0.0, NEWS for Ruby 3.4.0, NEWS for Ruby 3.3.0 and Bundler compatibility with Ruby