Upgrading from Rails 7 to Rails 8, step by step
An application on Rails 7.0, 7.1 or 7.2 reaches Rails 8 one minor version at a time: 7.1, 7.2, 8.0 and then 8.1. Every Rails 7 series and Rails 8.0 have reached end of life, so Rails 8.1 is the target. Ruby often takes more work than Rails, because Rails 7.2 needs Ruby 3.1 and Rails 8 needs Ruby 3.2. Many of the other changes are announced by deprecation warnings one version earlier.
The upgrade path from Rails 7.0 to Rails 8.1
- Rails 7.1 needs Ruby 2.7 or newer. Composite primary keys, a generated Dockerfile, and normalised configuration defaults.
- Rails 7.2 needs Ruby 3.1 or newer. Ruby 3.1 becomes the minimum and YJIT is on by default. Often the step that forces a Ruby upgrade first.
- Rails 8.0 needs Ruby 3.2 or newer. Propshaft replaces Sprockets as the default, Solid Cache, Solid Queue and Solid Cable replace their Redis-backed equivalents, and Kamal 2 ships with the app.
- Rails 8.1 needs Ruby 3.2 or newer. The current series. Active Job continuations, structured event reporting and a local CI runner arrive.
Before you start
The safest upgrade starts with knowing what the application does. The official upgrade guide puts test coverage first: without automated tests, every part of the application that a new version touches has to be checked by hand.
Write down the exact starting point: the rails line in Gemfile.lock, the
Ruby version in .ruby-version or the Gemfile, and the gems that depend on
Rails. Gems are often what sets the pace, because each Rails step needs a
release of every gem that supports it.
How each step works
Every step on the path above follows the same routine from the official upgrade guide:
- Make sure the tests pass on the latest patch release of the current series, and fix the deprecation warnings it shows.
- Change the Rails version in the
Gemfileand runbundle update rails. If the application uses Rails JavaScript packages, update them inpackage.jsontoo. - Run
bin/rails app:updateand review each file it offers to change. - Run the tests and deploy with the previous version’s framework defaults.
- Turn on the new defaults one by one from
config/initializers/new_framework_defaults_X_Y.rb, over as many deploys as needed, then setconfig.load_defaultsto the new version.
The last step is where behaviour can change quietly, so it is worth taking slowly. Each default is one line, and a problem is easy to trace back to it.
Rails 7.0 to 7.1
The upgrade guide’s longest section of the four. It lists, among others:
- A new cache format. For a rolling deploy, keep the old format on the first deploy and turn on the 7.1 format in a later one, so servers that are not yet upgraded can still read the cache.
- Autoloaded directories leave
$LOAD_PATH. Code that loads application files with a manualrequirestops working. Applications that autoloadlibcan switch toconfig.autoload_lib. - Active Record Encryption uses SHA-256. An application that already encrypts data may have to configure the digest it used before, so that existing data can still be decrypted.
@rails/ujsimports change. Functions are imported through theRailsobject, not one by one.- The SQLite adapter uses strict strings. Double-quoted string literals in SQL stop working.
Rails 7.1 to 7.2
- Ruby 3.1 is the minimum. This is often the step that forces a Ruby upgrade first.
Rails.application.secretsis removed. Secrets move to encrypted credentials. Rails 7.1 already warned about this.- Tests follow the configured job adapter. If the application sets
config.active_job.queue_adapter, every test now uses it, and tests that relied on the test adapter can fail. alias_attributeno longer calls custom methods on the original attribute. Rails 7.1 warned about each case.
Rails 7.2 to 8.0
- Ruby 3.2 is the minimum.
- The upgrade guide lists no specific changes for this step. The release
notes list removals of things already deprecated, such as
config.read_encrypted_secretsand defining anenumwith keyword arguments. - The new defaults are for new applications. Propshaft, Solid Cache,
Solid Queue, Solid Cable and Kamal 2 are what
rails newsets up. The upgrade guide does not ask an existing application to adopt them.
Rails 8.0 to 8.1
schema.rbsorts table columns alphabetically. Expect one large, harmless diff the first time the schema is dumped.- A short list of removals, all deprecated earlier: the
:azurestorage service, semicolons as a query-string separator,bin/rake statsand the SQLite adapter’s:retriesoption. The built-in Sidekiq adapter is deprecated and now comes with thesidekiqgem.
The Rails 8.0 end-of-life page covers this step in more detail.
Ruby along the way
Plan Ruby upgrades as their own steps, each with its own deploy. The upgrade guide’s advice is to upgrade Ruby first, as far as the current Rails version allows. Which Ruby versions a series runs on beyond its minimum depends on its patch release and on the gems, so check both before you start. The Rails end-of-life overview lists which Ruby branches still get security fixes.
Where these facts come from
The steps, the per-version changes and the advice above come from the official Upgrading Ruby on Rails guide and the release notes for 7.2, 8.0 and 8.1. The path above, its Ruby versions and the support dates come from the same data as the end-of-life pages, which an automated check compares with the official sources every week.
Common questions
Can we upgrade from Rails 7.0 straight to Rails 8.1?
The official upgrade guide recommends against it: move one minor version at a time, to the latest patch of each. Each version warns about what the next one changes or removes, so skipping a version means meeting those changes without the warnings. On a large application, the separate steps also keep every change small enough to trace.
Do we have to switch to Propshaft, Solid Queue and Kamal in Rails 8?
No. They are the defaults for new Rails 8 applications. For existing applications, the official upgrade guide lists no change that must be made for them between Rails 7.2 and 8.0, so an application can adopt them later, one at a time, or not at all.
Should we upgrade Ruby first?
The official upgrade guide advises upgrading Ruby and Rails separately, and Ruby first, to the newest version you can. Rails 7.2 needs Ruby 3.1 or newer and Rails 8.0 and 8.1 need Ruby 3.2 or newer. Ruby 3.2 itself reached end of life on 1 April 2026, so aim for a supported Ruby, not just the minimum.
How long does an upgrade from Rails 7 to Rails 8 take?
It depends on where the application starts, its test coverage, its dependencies and how many deprecation warnings it shows today. An application on 7.2 with good tests and current gems has a shorter path than one on 7.0 with neither. Discovery turns that estimate into a fixed price.
Check your application
See which Rails era your application shows the outside world. One page, one request, and nothing about you is stored.
Check your application →Talk to an engineer
In thirty minutes, an engineer can help you decide whether an upgrade is worth investigating. No commitment.
Book a free call ↗