nokogiri requires Ruby version >= 3.0, < 3.4.dev. The current ruby version is 2.6.10.210

Published by Moncef Belyamani on

If you just tried to install Rails on your Mac, most likely with gem install rails --user-install or sudo gem install rails, then you probably got an error saying “nokogiri requires Ruby version >= 3.0”:

ERROR: Error installing rails:

The last version of nokogiri (>= 1.8.5) to support your Ruby & RubyGems was 
1.13.10. Try installing it with `gem install nokogiri -v 1.13.10` and then 
running the current command again

nokogiri requires Ruby version >= 3.0, < 3.4.dev. The current ruby version is 
2.6.10.210.

Before jumping to the solution, there are a few things going on here that are important to understand:

How Ruby gems work

A gem is a way to package Ruby code so that it can be easily installed on a computer. Some gems are very small and can provide a very specific functionality to an existing app, such as a Rails app. Other gems, like Rails, are much more complex and require many other gems to work properly.

These required gems are known as dependencies because the main gem depends on them to work. Without those dependencies, the main gem would not work. To see the dependencies of a particular gem, you can look it up on rubygems.org.

For example, here is the rubygems page for the latest version of Rails. You can see that it has 13 main dependencies, but each of those dependencies might have their own dependencies. So, the total number of gems Rails depends on is a lot more than 13.

In addition to depending on specific versions of other gems, many gems also specify which versions of Ruby they support. If you look at the sidebar on the right of the Rails page on rubygems.org, you’ll see that the required Ruby version is at least 2.7.0 for the latest version of Rails.

Similarly, if you look up nokogiri on rubygems.org, you’ll see that the latest version requires Ruby >= 3.0.0.

How gem installation works

When you run gem install without specifying a version, your computer looks up the latest version of the gem by default. Then it starts by trying to install all the dependencies of the main gem you want to install. If a dependency has a minimum required Ruby version, then that gets checked as well.

This is why when you try to install Rails while using Ruby 2.6.10, it complains that “nokogiri requires Ruby version >= 3.0”. nokogiri is one of the many gems that Rails depends on, and the latest version of nokogiri requires Ruby version greater than or equal to 3.0, but less than 3.4.dev.

Why the current Ruby version is 2.6.10

macOS 14.x (Sonoma), macOS 13.x (Ventura), and 12.6.x (Monterey) come preinstalled with Ruby 2.6.10, which is why you can run ruby -v out of the box and get an answer. Similarly, you can run gem install and it won’t complain that the gem command is not found.

However, the version of Ruby that comes preinstalled on a Mac, known as the system Ruby, is not meant to be used for development. If you run irb -v while using the system Ruby, you’ll see this warning from Apple:

WARNING: This version of ruby is included in macOS for compatibility with 
legacy software.
In future versions of macOS the ruby runtime will not be available by
default, and may require you to install an additional package.

For more details, read my article that goes over 5 reasons why you shouldn’t use the system Ruby. If you’re not convinced, Don’t Use System Ruby is another site that warns against this.

What happens if you install gems with the system Ruby

If you try to install a gem on a fresh macOS installation with just gem install, such as gem install rails, you will get the error you don’t have write permissions for the /Library/Ruby/Gems/2.6.0 directory.

That’s because the default location where gems would get installed is /Library/Ruby/Gems/2.6.0, but Apple doesn’t give you permission to write to that directory. Unfortunately, you’ll still find bad advice to override Apple’s protection with sudo. Please, never use sudo to install gems, even if you’re not using the system Ruby!

Although the solution to add --user-install is safer (because it installs the gems in ~/.gem/ruby/2.6.0/bin, which you have permissions to write to), it still uses the system Ruby, and it can lead to other issues such as:

How to properly install Rails on a Mac

In this particular case, the issue is that the system Ruby is too old for the latest version of Rails. One solution would be to use an older version of Rails that works with Ruby 2.6.10, but I wouldn’t recommend that for two reasons:

  • The system Ruby shouldn’t be used to install gems
  • You’re missing out on new features, performance improvements, and security fixes that might not be available in older Rails versions

Similarly, you could try installing an older version of Nokogiri, as suggested in the error message, but you would still run into the same issues as above.

Note that even if macOS came with Ruby 3.0 or higher, you still shouldn’t use the system Ruby to install Rails. Instead, you want to install a separate and newer version of Ruby using a special tool that lets you install multiple versions of Ruby at the same time, and easily switch between them.

These tools are known as version managers, and the most popular ones are asdf, chruby, frum, rbenv, and rvm. Even if you’re using Ruby for the first time, it’s worth your time to learn how to use a Ruby version manager because you will inevitably need one.

Over the past twelve years, I’ve helped hundreds of thousands of people set up Ruby on their Mac.

From clean Macs to the most obscure issues, I’ve seen and fixed it all. And the most reliable solution is to use a version manager. My personal favorite is chruby because it’s the simplest, fastest at switching between Ruby versions, and least likely to cause issues.

Here are my two recommended ways to set up a proper Ruby development environment on a Mac:

  • Have everything set up for you in 15 minutes or less with a single terminal command
  • Spend an hour or more setting everything up manually

Have everything set up for you in 15 minutes or less with a single command

Ruby on Mac is the easiest, fastest, and most reliable way to set up, restore, and maintain a proper Ruby dev environment on a Mac. It also automatically installs Rails for you, as well as all the other development tools you’ll need for Rails. It can automatically fix your outdated or misconfigured development setup in minutes, saving you from having to wipe your computer and reinstall macOS.

It will save you so much time and frustration.

But don’t just take my word for it. Read 150+ testimonials that show how much people love Ruby on Mac.

Spend an hour or more setting everything up manually

If you prefer to spend an hour or more doing everything manually, you can follow my free step-by-step guide for installing Ruby on a Mac. The guide works best when you start with a clean development environment.

Depending on how messy your setup is, you might need to spend additional time uninstalling some or all dev tools. In the worst case, you’ll need to spend a few more hours backing up your computer, reformatting the hard drive, and reinstalling macOS.