Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

flutter doctor says CocoaPods is installed but not working

ErrorCocoaPods installed but not working.

Short answer

Flutter runs pod --version and treats a failed or unreadable result as a broken install. The tool says this often happens when the Ruby that installed CocoaPods differs from the Ruby now used to run it, and that reinstalling usually fixes it. Find which pod runs, then reinstall the gem with the Ruby you actually use.

  • Applies to Flutter 3.x, CocoaPods 1.16, macOS 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the same command Flutter runs. If it fails or prints no version, you see the real error.

    which -a pod
    pod --version
  2. 2Match what you see, then jump to its fix

    1. 1pod --version fails with a Ruby or gem errorCocoaPods was installed with a different Ruby than the one running itFix
    2. 2gem install fails with a permission error, or pod is not found after a sudo-less installGems were installed for the system Ruby without the right permissions or pathFix
    3. 3Warning: CocoaPods minimum required version 1.10.0 or greater not installed.CocoaPods is older than Flutter acceptsFix

What does the error look like?

  • CocoaPods installed but not working.
  • You appear to have CocoaPods installed but it is not working.
  • Warning: CocoaPods is installed but broken. Skipping pod install.

Cause 1 of 3

CocoaPods was installed with a different Ruby than the one running it

1Check

Flutter's own message names this case. See which ruby is first on the PATH and which gem command you used.

which ruby
ruby --version
which gem

2Fix

Reinstall CocoaPods with the Ruby you use now. The CocoaPods guide says to install the gem again to update it; repeat the sudo if you used sudo the first time.

sudo gem install cocoapods

3Verify

pod prints a version and flutter doctor stops warning.

pod --version
flutter doctor

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 2 of 3

Gems were installed for the system Ruby without the right permissions or path

1Check

The system Ruby needs sudo for gem install. Without sudo, the gem goes to a user directory that must be on the PATH.

gem environment

2Fix

Either use sudo, or install a separate Ruby with Homebrew or a version manager, or install with --user-install and add the gem bin directory to your PATH.

gem install cocoapods --user-install

3Verify

A new terminal finds pod.

which pod && pod --version

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 3 of 3

CocoaPods is older than Flutter accepts

1Check

Flutter's tool requires at least 1.10.0 and recommends 1.16.2 or newer. Compare your version.

pod --version

2Fix

Install the gem again; the guide says that is how to update, and --pre is only for pre-release versions.

sudo gem install cocoapods

3Verify

pod --version shows a current version and flutter doctor is clean.

flutter doctor

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Pick one way to install Ruby gems (system with sudo, or a Ruby manager) and keep to it.
  • After changing the Ruby version, reinstall CocoaPods before running flutter.
  • Run flutter doctor after each macOS or Xcode update.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.