Rails 5 or 6 to Rails 7 or 8: an upgrade checklist

To upgrade a Rails 5 or 6 app to Rails 7 or 8, work in this order: get tests around the flows that make money, upgrade Ruby to a version the next Rails needs, then move Rails one minor version at a time, fixing deprecations at each step and switching on the new framework defaults gradually. Plan for the step from Rails 6.1 to 7.0, where the classic autoloader is gone and every app must run on Zeitwerk. Skipping versions saves no time; it hides the warnings that tell you what will break.

This checklist is for founders and CTOs whose Rails app works but runs on a version that no longer gets security fixes.

Why the deadline is real

The Rails team announced in October 2025 that Rails 7.0 and 7.1 have reached end of life and will no longer receive security or bug fixes. The same announcement lists security support for Rails 7.2 until August 9, 2026, Rails 8.0 until November 7, 2026, and Rails 8.1 until October 10, 2027. By those dates, an app on Rails 7.2 or earlier is already outside security support, and Rails 8.0 follows in November 2026. Rails 5 and 6 have been out of support for longer. The current list is on the Rails maintenance policy page. For the reasoning behind upgrading instead of rebuilding, see Upgrading an old Rails app without a rewrite.

Before you change a version number

1. Write down where you are. Rails version, Ruby version, database, hosting, background job system, and how deploys happen.
2. List the gems. Mark the ones with no recent release, the ones pinned to old versions, and any forks. These decide the order of the upgrade more than Rails does.
3. Add tests around critical paths. Checkout, billing, sign-in, and the reports people rely on. The official Rails upgrade guide is direct about this: without a test suite, you have to check every changed part of the app by hand.
4. Turn on error tracking and deprecation logging in production. You want to see warnings before they turn into errors.
5. Agree the target. For most apps that is the current supported Rails release, reached in steps, not in one jump.

Ruby comes first

Each Rails version needs a minimum Ruby version. The upgrade guide lists them:

Rails version	Minimum Ruby
Rails 5	Ruby 2.2.2
Rails 6	Ruby 2.5.0
Rails 7.0 and 7.1	Ruby 2.7.0
Rails 7.2	Ruby 3.1.0
Rails 8.0 and 8.1	Ruby 3.2.0

The guide recommends upgrading Ruby and Rails as separate steps, Ruby first. Ruby has its own support schedule on the Ruby branches page, so check that the Ruby you land on is still maintained, not just the minimum Rails accepts.

The checklist for each version step

Repeat this for every minor version between where you are and where you are going, for example 6.0, 6.1, 7.0, 7.1, 7.2, 8.0, 8.1.

1. Move to the latest patch of your current version and fix any new deprecation warnings.
2. Change the Rails version in the Gemfile to the latest patch of the next minor version and run bundle update rails. Update gems that block the resolve, one at a time.
3. Run bin/rails app:update and review every file it wants to change. Do not accept all overwrites; your config holds decisions someone made for a reason.
4. Leave config.load_defaults where it is for now. The update task creates a new_framework_defaults initializer. Turn those new defaults on one or a few at a time, across more than one deploy if needed.
5. Run the test suite and fix failures, then check the critical paths by hand in a staging environment that looks like production.
6. Deploy the step on its own and watch error tracking before starting the next one.
7. Once every new default is on, delete the defaults initializer and raise config.load_defaults to the new version.

Where Rails 5 and 6 apps usually get stuck

• Autoloading. Rails 6 introduced Zeitwerk as the default autoloader but let apps keep the classic one. In Rails 7.0 the classic autoloader is removed, so file and constant names have to follow Zeitwerk's conventions before you cross that line. Do this work on Rails 6.x, where you can still switch back.
• Abandoned gems. A gem that stopped at Rails 6 support can block every later step. Replace it, fork it, or remove the feature that depends on it, and decide which before you start.
• Front-end build tools. Older apps often depend on an asset or JavaScript setup that newer Rails versions no longer default to. Keep what you have working first; change the front-end build as its own project.
• Framework defaults left off. Apps that upgraded the gem but never moved load_defaults carry old behavior forward, and the gap grows with every version.
• Background jobs and integrations. Jobs, webhooks, and external APIs fail quietly. Check that queues drain and syncs still run after each deploy.

If you want a second opinion on your upgrade path, bring your Rails and Ruby versions and your Gemfile to a Systems Discovery Call. We will tell you the order we would upgrade in and what to test first.

How we run Rails upgrades

We start with a written assessment of the current Rails and Ruby versions, gem dependencies, deprecations, and the order to upgrade in. Then we add tests around checkout, billing, auth, and other critical paths, and move one minor or major version at a time while the app stays live. After the upgrade, the same team keeps the app current so it does not fall behind again. We have shipped Rails in production for 10+ years, including Zentap, a Rails platform used by 20,000+ real estate agents that we work on long-term. The details are on our Rails upgrade services page, and if the original developer has left, see Rails app takeover and maintenance.

Common questions

Can we jump straight from Rails 6 to Rails 8?

You can change the version number, but you lose the deprecation warnings that each step gives you, and every problem arrives at once. Moving one minor version at a time is usually faster in practice because each step is small enough to test and deploy safely.

Do we need a code freeze during the upgrade?

Usually not. Each step ships as a small, tested release, so feature work can continue in between. Agree with the team which areas are being upgraded so changes do not collide.

Is a rewrite ever the better choice?

Sometimes, if the business has changed so much that most of the code no longer fits. Most of the time, a rewrite throws away years of business logic, and a stepwise upgrade keeps what works and modernizes the framework underneath it.

Next step

If your app is on Rails 5, 6, or 7 and you need a plan, book a Systems Discovery Call. It is 45 minutes on your application and its versions, and you leave with a clear view of the upgrade path and what to do first, whether you hire us or not.