How to fix "CocoaPods installed but not working" in Flutter

Published by Moncef Belyamani on

Have you been trying for days to install cocoapods on your Apple Silicon Mac so you can start using Flutter? You’ve probably tried all the solutions on the net, but nothing so far has worked.

Well, today is your lucky day!

You’re probably getting the common error “CocoaPods installed but not working” when running flutter doctor, as shown below:

✗ CocoaPods installed but not working.
  You appear to have CocoaPods installed but it is not working.
  This can happen if the version of Ruby that CocoaPods was installed with is different from the one being used to invoke it.
  This can usually be fixed by re-installing CocoaPods.
To re-install see https://guides.cocoapods.org/using/getting-started.html#installation for instructions.

Here are common causes of this error:

  • Cocoapods is not installed and configured properly in your development environment

  • You have multiple Cocoapods installations. For example, with both Homebrew and via gem install cocoapods. You can check by running which -a pod.

  • You installed cocoapods using the system Ruby (Ruby 2.6.10 that came preinstalled on your Mac), using either sudo gem install cocoapods or gem install cocoapods --user-install

  • You installed Ruby with Homebrew instead of using a version manager.

  • You installed Ruby with both Homebrew and with one or more version managers.

  • You’re on an Apple Silicon Mac and you installed development tools both with and without Rosetta. One way to check is if you have files under both /usr/local and /opt/homebrew.

Unfortunately, the official instructions on the Cocoapods website are not the ones I would recommend. I’m surprised that they recommend using sudo because it’s dangerous and can lead to all kinds of issues. Learn why would should never use sudo to install gems.

They also recommend using the standard Ruby available on macOS instead of a version manager, which is also the complete opposite of what I would recommend, especially for people new to Ruby. Here are 5 reasons why you shouldn’t use the system Ruby. And I’m not the only one to warn about this. Check out the Don’t Use System Ruby site as well.

So what’s the proper way to install Cocoapods on a Mac?

Glad you asked! The most reliable method, and the only one I recommend, is to install a separate and newer version of Ruby using a version manager. If you’re really interested in all the possible options, including ones I don’t recommend (such as installing Ruby with Homebrew), read my definitive guide to installing gems on a Mac.

I highly recommend using a Ruby version manager because it allows you to have multiple versions of Ruby installed at the same time, and makes it easy to switch between them. Even if you’re using Ruby for the first time, it’s worth your time to learn how to use a Ruby 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, specifically chruby and ruby-install.

Install Ruby with a version manager

At a high level, there are a minimum of five steps to a working Ruby environment on macOS with a Ruby manager:

  1. Install Homebrew (which will also install the prerequisite Apple command line tools)
  2. Install a Ruby version manager such as chruby and ruby-install (others include asdf, frum, rbenv, and RVM)
  3. Configure the Ruby version manager
  4. Install a specific version of Ruby
  5. Switch to that version of Ruby

You have two options for performing those steps:

  • 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 and maintain a proper Ruby dev environment on a Mac. It can automatically fix your outdated or misconfigured development setup in minutes, saving you from having to wipe your computer and reinstall macOS. It also automatically installs all the other development tools you’ll need for Rails, Jekyll, 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 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.