Ruby 4.0 Adoption Guide: What Changed, What Breaks, and How to Upgrade

Ruby 4.0.0 shipped on December 25, 2025, and the first patch release (4.0.1) followed on January 13, 2026. This is the first major version bump since Ruby 3.0 landed in 2020, and it brings real changes: a new JIT compiler (ZJIT), an experimental isolation primitive (Ruby Box), Ractor communication overhaul, and a wave of standard library promotions that will affect your Gemfile. This guide covers what matters for production teams migrating from Ruby 3.x.

Sources: This article is based on the official Ruby 4.0.0 release announcement and the Ruby 4.0.1 patch notes from ruby-lang.org.

Key Ruby 4.0 Changes

ZJIT: The Next-Generation JIT Compiler

Ruby 4.0 introduces ZJIT, a new JIT compiler that requires Rust 1.85.0+ to build. Enable it with the --zjit flag. ZJIT is currently faster than the interpreter but does not yet match YJIT's performance. The Ruby team recommends against deploying ZJIT in production until Ruby 4.1. YJIT remains available and is still the recommended JIT for production workloads.

# Continue using YJIT in production
ruby --yjit app.rb

# Try ZJIT in development/staging only
ruby --zjit app.rb

# Note: --rjit has been removed in Ruby 4.0

Ruby Box (Experimental Isolation)

Ruby Box provides definition-level isolation for monkey patches, global variables, class variables, and library mutations. Enable it with RUBY_BOX=1. Use cases include isolated test execution, parallel web app deployment in the same process, and evaluating untrusted gem behavior. This is experimental and the API may change, but it signals the direction Ruby is heading for multi-tenant isolation.

Ractor Overhaul

Ractors received major changes in 4.0. The old communication primitives (Ractor.yield, Ractor#take, Ractor#close_incoming, Ractor#close_outgoing) have been removed and replaced with Ractor::Port for inter-Ractor communication. New methods include Ractor#join, Ractor#value, and Ractor.shareable_proc. If you use Ractors, this is a breaking change that requires code updates.

Set Promoted to Core

Set is now a core class, no longer requiring require "set". It also has a new display format: Set[1, 2, 3] instead of #<Set: {1, 2, 3}>. Code that parses Set#inspect output (in tests or logs) will need updating. Additionally, passing arguments to to_set is now deprecated.

Pathname Promoted to Core

Pathname has been promoted from a default gem to a core class. The require "pathname" call is no longer necessary but will not break existing code.

Language and Syntax Changes

• *nil change — *nil no longer calls nil.to_a. Code relying on this implicit conversion will break
• Logical operators as line continuations — ||, &&, and, or at the start of a line now continue the previous line, similar to the fluent dot (.) syntax
• Unicode 17.0.0 and Emoji 17.0 — String methods updated to the latest Unicode standard
• String#strip accepts selectors — strip, lstrip, and rstrip now accept *selectors arguments for fine-grained whitespace control

Performance Improvements

Ruby 4.0 delivers meaningful performance gains even without ZJIT:

• Class#new is faster in all cases, especially with keyword arguments
• Instance variable access is faster via new internal "fields" objects
• GC improvements — Independent heap growth by size pool, faster sweeping for large objects
• object_id and hash are faster on Class and Module
• Ractor performance — Lock-free symbol table, per-Ractor allocation counters, reduced contention

Migration Strategy: Ruby 3.x to 4.0

A major version upgrade requires more care than a minor one. Here is the recommended approach:

Step 1: Get to Ruby 3.4 First

If you are on Ruby 3.2 or 3.3, upgrade to 3.4 first. Ruby 3.4 introduced deprecation warnings for APIs that are removed in 4.0. Running your test suite on 3.4 with RUBYOPT="-W:deprecated" will surface most issues before you hit hard errors on 4.0.

Step 2: Audit Breaking Changes

The following removals and changes are most likely to affect real-world codebases:

• Removed --rjit — If your deployment scripts reference --rjit, switch to --yjit
• Removed pipe-based Kernel#open and IO process creation — Use IO.popen explicitly
• Bundled gem promotions — ostruct, logger, irb, rdoc, benchmark, and pstore are now bundled gems. If you require them without listing them in your Gemfile, you will get warnings or errors
• Net::HTTP header change — Automatic Content-Type: application/x-www-form-urlencoded header is no longer added for requests with a body. If your API clients depend on this, set the header explicitly
• SortedSet removed — Install the sorted_set gem separately if needed
• CGI library reduced — Only cgi/escape remains. If you use other CGI functionality, add the cgi gem to your Gemfile
• Bundler 4.0 and RubyGems 4.0 — Ships with Bundler 4.0.3 and RubyGems 4.0.3. Check for compatibility with your CI/CD scripts

Step 3: Separate Ruby and Rails Upgrades

If you are also planning a Rails upgrade, do not combine it with the Ruby 4.0 jump. Upgrade Ruby first on your current Rails version, stabilize, then upgrade Rails separately. Mixing both creates a debugging nightmare when something breaks.

Gem Compatibility Checks

Ruby 4.0 is a major version bump, and gem compatibility is the biggest risk factor. Here is how to assess your exposure:

# 1. Update .ruby-version to 4.0.1 and try bundling
bundle install

# 2. If gems fail to install, try conservative updates
bundle update --conservative

# 3. Check for gems that pin ruby version constraints
grep -r "required_ruby_version" vendor/bundle/ | grep -v "4.0"

# 4. For gems with C extensions, force recompilation
bundle pristine

# 5. Run your full test suite with deprecation warnings
RUBYOPT="-W:deprecated" bundle exec rspec

Gems that commonly need attention during a Ruby 4.0 upgrade:

• ostruct / logger / irb / benchmark — Now bundled gems. Add them to your Gemfile if you require them directly
• Gems using Ractor.yield or Ractor#take — These APIs are removed. Check for updated gem versions that use Ractor::Port
• Nokogiri, pg, mysql2 — C extension gems need recompilation. Run bundle pristine after upgrading Ruby
• Puma — Ensure you are on Puma 6+ for Ruby 4.0 compatibility
• RSpec — The it block parameter (introduced in Ruby 3.4) continues to conflict with RSpec's it. Latest RSpec handles this, but custom matchers may still produce warnings
• OpenSSL — Ships with openssl 4.0.0. Gems that pin older openssl versions may need updating
• Gems parsing Set#inspect or Proc#parameters output — Both formats have changed

Performance and CI Implications

Ruby 4.0 changes several things that affect your CI pipeline and production performance monitoring:

• Build toolchain — If you want ZJIT support (even for testing), your build environment needs Rust 1.85.0+. This affects Docker images, CI runners, and build servers. YJIT does not require this
• Error backtraces — Backtraces now include receiver class/module names (e.g., Foo#bar) and no longer show internal C frames. Error monitoring tools (Sentry, Honeybadger, Rollbar) should handle this, but verify that your log parsing and alerting rules still match
• Memory profile — The new "fields" objects for instance variables and variable-width allocation for larger integers change memory layout. Re-baseline your memory monitoring after upgrading
• CI matrix — Add Ruby 4.0 to your CI matrix alongside 3.4. Drop Ruby 3.2 and earlier, which are past end-of-life. Run with RUBYOPT="-W:deprecated" on 4.0 to catch forward-looking deprecations
• Bundler 4.0 — Ships with Bundler 4.0.3. If your CI caches vendor/bundle, clear the cache after upgrading to avoid stale native extensions

Production Rollout Checklist

Follow this order to minimize surprises:

Further Reading

• Ruby 4.0.0 Release Announcement
• Ruby 4.0.1 Patch Release
• YJIT Documentation
• Ruby News — All Release Announcements