cocoapods-downloader requires Ruby version >= 2.7.4. The current ruby version is 2.6.10.210

Published by Moncef Belyamani on
Updated on

If you just tried to install the latest version of cocoapods on your Mac, most likely with sudo gem install cocoapods or gem install cocoapods --user-install, then you probably got an error saying “cocoapods-downloader requires Ruby version >= 2.7.4”:

ERROR:  Error installing cocoapods:
There are no versions of cocoapods-downloader (>= 2.0) compatible with 
your Ruby & RubyGems. Maybe try installing an older version of the gem 
you're looking for?

cocoapods-downloader requires Ruby version >= 2.7.4. The current ruby 
version is 2.6.10.210.

If you’ve been using cocoapods for a while, this might seem surprising because all this time, the official advice from the Cocoapods team was to install cocoapods using the version of Ruby that came preinstalled on your Mac.

Unfortunately, that is bad advice, and I recommend that you unlearn it. Keep reading to understand why this is happening now, and how to fix it.

How Ruby gems and gem versions work

A gem is a way to package Ruby code so that it can be installed on a computer. Many gems are also made up of other gems. These 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 cocoapods. You can see that the latest version has 17 runtime dependencies, but each of those dependencies might have their own dependencies. So, the total number of gems cocoapods depends on is a lot more than 17.

Not only that, but each gem depends on specific versions of other gems, and many gems also specify which versions of Ruby they support. If you look at the sidebar on the right of the cocoapods page on rubygems.org, you’ll see that the required Ruby version is at least 2.7 for the latest version of cocoapods.

This minimum Ruby version is determined by looking at ALL of the dependencies, checking which Ruby version each one requires, and picking the highest one. In this case, the requirement of 2.7 or greater is coming from the cocoapods-downloader gem, which requires 2.7.4 or higher.

This just happened recently when cocoapods-downloader version 2.0 was released on October 26, 2023. Before that, cocoapods-downloader required Ruby >= 2.3.3. On that same day, cocoapods version 1.14.0 was released, and it changed its dependency on cocoapods-downloader from versions less than 2.0 to versions 2.0 and higher.

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 cocoapods while using Ruby 2.6.10, it complains that “cocoapods-downloader requires Ruby version >= 2.7.4”. cocoapods-downloader is one of the many gems that cocoapods depends on, and the version of cocoapods-downloader that the latest version of cocoapods depends on requires Ruby version greater than or equal to 2.7.4.

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 try to install a gem on a fresh macOS installation with just gem install, such as gem install cocoapods, 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:

For more details, read my article that goes over 5 reasons why you shouldn’t use the system Ruby.

How to properly install the latest version of cocoapods on a Mac

In this particular case, the issue is that the system Ruby is too old for the latest version of cocoapods. One solution would be to use an older version of cocoapods 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 cocoapods versions

Note that even if macOS came with Ruby 2.7.4 or higher, you still shouldn’t use the system Ruby to install cocoapods. 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.

Also, when cocoapods says it needs Ruby 2.7.4 or higher, it doesn’t mean that you need to install 2.7.4 specifically. In fact, Ruby 2.7 already reached end of life, so you shouldn’t be using it for new projects. Cocoapods works fine with newer Ruby versions like 3.2.3, so that’s what I recommend you install.

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 preference is chruby with ruby-install because they’re the least complex and one of the fastest at switching between Ruby versions.

There are two 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 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 and maintain a proper Ruby dev environment on a Mac. It also automatically installs all the other development tools you’ll need for Cocoapods, Flutter, React Native, or any other project that depends on Ruby. It will save you so much time and frustration.

When you buy Ruby on Mac today, you’ll be supporting an independent developer and his family. And if you need it for your job or business, you should be able to expense it.

Read more about what makes Ruby on Mac special and how much people love Ruby on Mac.

Spend an hour or more setting everything up manually

If you haven’t yet tried to install Ruby or other development tools on your Mac, you should be able to get up and running with the basics by following my free step-by-step guide for installing Ruby on a Mac.