Ruby 3.1 on Rails

ruby31onrails.md

Ruby 3.1 on Rails

Actions required to use Ruby 3.1.0 with Rails

Rails 7.0.Z

• Rails 7.0.1 is compatible with Ruby 3.1.0.
• Rails 7.0.1 addes net-smtp, net-imap and net-pop gems as Action Mailbox and Action Mailer dependency, you do not need to add them explicitly in your application Gemfile anymore.
• thor 1.2.1 has been released. You will not see DidYouMean::SPELL_CHECKERS.merge deprecate warnings anymore.

Rails 6.1.Z

• Use Rails 6.1.5 to support database.yml with aliases and secrets.yml with aliases.

Rails 6.0.Z

• You will likely get this error.

  Psych::BadAlias: Unknown alias: default

• Upgrade to Rails 6.1.5 or higher.
• No Psych 4 support has been backported to Rails 6.0. Use Psych 3 as a workaround.

  gem "psych", "~> 3.0"

---

Details - if you are interested

Maintenance Policy for Ruby on Rails

https://guides.rubyonrails.org/maintenance_policy.html As of Dec 25, 2021, Supporting Ruby 3.1 with Rails should not be security issues.

• Rails 7.0.Z accepts bug fixes.
• Rails 6.1.Z accepts security issues only.
• Rails 6.0.Z accepts severe security issues only.

---

Changes to support Ruby 3.1

• Add Class#descendants
• Psych 4 support
• net-smtp, net-imap, net-pop are bundled gems
• Ruby 3.1 performance optimization
• DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated.

---

Add Class#descendants

• Rails 7.0.0 expects Ruby 3.1 has both of Class#descendants and Class#subclasses or not.

• Ruby 3.1 supports Class#subclasses only, Class#descendants has been removed on Dec 21, 2025.

• Rails 7.0.0 did not expect one of these methos removed.

• Rails 7.0.1 supports Ruby 3.1 Class#subclasses.

• Related pull requests at Ruby

  • ruby/ruby#4974
  • ruby/ruby#5070
  • ruby/ruby#5097
  • ruby/ruby#5309

• Related pull requests at Rails

  • rails/rails#43548
  • rails/rails#43722
  • rails/rails#43723
  • rails/rails#43481
  • rails/rails#43970

---

Psych 4 support

• Ruby 3.1.0 installs Psych 4.0.3 as standard library

  • Use Psych.safe_load by default

  • https://www.ruby-lang.org/en/news/2021/12/25/ruby-3-1-0-released/

    Psych 4.0 changes Psych.load as safe_load by the default. You may need to use Psych 3.3.2 for migrating to this behavior. [Bug #17866]

• Psych 4 support at Rails

  • Included to Rails 6.1.4 or later

    • rails/rails#42249
    • rails/rails#42257

  • Included to Rails 6.1.5 or later

    • rails/rails#42687

---

YAML files used in Rails

• config/database.yml

  default: &default
    adapter: sqlite3
    pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
    timeout: 5000
  
  development:
    <<: *default
    database: db/development.sqlite3
  
  # Warning: The database defined as "test" will be erased and
  # re-generated from your development database when you run "rake".
  # Do not set this db to the same as development or production.
  test:
    <<: *default
    database: db/test.sqlite3
  
  production:
    <<: *default
    database: db/production.sqlite3

• config/secrets.yml (Rails 4.1+) or config/secrets.yml.enc (Rails 5.1+)
  • You will get this error run Rails 6.1 with Ruby 3.1.0

  $ bin/rails s
  => Booting Puma
  => Rails 6.1.4.4 application starting in development
  => Run `bin/rails server --help` for more startup options
  Exiting
  /home/yahonda/.rbenv/versions/3.1.0-dev/lib/ruby/3.1.0/psych/visitors/to_ruby.rb:430:in `visit_Psych_Nodes_Alias': Unknown alias: default (Psych::BadAlias)

• config/credentials.yml.enc
  • Included to Rails 7.0.2 or later
  • rails/rails#44063

---

net-smtp, net-imap, net-pop are bundled gems

• No need to add net-smtp, net-imap, net-pop gems manually for Rails 7.0.1+
• If you need to use mail gem, add them explicitly in your Gemfile if you are running Rails 6.1 or lower with Ruby 3.1.
• mikel/mail#1439
• rails/rails#44083 has been merged to Rails main and backported to 7-0-stable branch.

---

Ruby 3.1 performance optimization

• Optimize dynamic string interpolation for symbol/true/false/nil/0-9 ruby/ruby#5002 rails/rails#43772 https://bugs.ruby-lang.org/issues/13715

---

did_you_mean gem shows this deprecation at thor

• Calling DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call DidYouMean.correct_error(error_name, spell_checker)' instead.
• thor v1.2.0 fixes it via rails/thor#761 .
• Use thor v1.2.1 which fixes a regression.

---

Enjoy Ruby 3.1!

Thanks for this really helpful and comprehensive guide!

Thanks! Very useful for me to do upgrade job.

Rails 6.0.Z part says "Upgrade to Rails 6.1.5 or higher." It's not very true.
I get over it! Now our application successfully to run Rails v6.0.6 with Ruby v3.1.3.

Please fix the date in this line:

Ruby 3.1 supports Class#subclasses only, Class#descendants has been removed on Dec 21, 2025.

It should be 2021