Fixing “CocoaPods Out of Date” in Flutter on macOS Sequoia and Sonoma

If you just updated macOS and Flutter suddenly refuses to build for iOS with a CocoaPods out of date error, you’re not alone — this one’s been showing up a lot since Sequoia rolled out. I hit it myself on a clean Sonoma-to-Sequoia upgrade and spent way longer than I’d like to admit chasing the wrong fix first. So let’s get into what’s actually going on and how to clear it without nuking your whole Ruby setup.

Quick answer:

• Run pod --version first — if it’s below 1.11.0, that’s your actual problem, not Flutter.
• Update CocoaPods with sudo gem install cocoapods (or via Homebrew if you went that route originally).
• If the update itself fails or hangs, it’s almost always a Ruby version conflict introduced by the macOS upgrade, not a CocoaPods bug.
• Delete ios/Podfile.lock and ios/Pods/ after updating, then run flutter clean before rebuilding.
• If none of that works, check whether you’re on system Ruby vs Homebrew Ruby — mixing the two is the most common root cause people miss.

Why This Keeps Happening After macOS Updates

This error isn’t really a Flutter bug. Flutter just checks your installed CocoaPods version against a minimum it needs, and when that check fails, it throws the warning. The actual cause sits a layer below, in your Ruby/CocoaPods setup, and macOS upgrades have a habit of disturbing that layer.

Cause 1: macOS Sequoia changed how system Ruby behaves. Apple has been slowly deprecating the bundled system Ruby for a while now, and Sequoia pushed that further. If CocoaPods was installed against the old system Ruby, an OS upgrade can leave you with a CocoaPods binary that’s technically still there but broken in ways that look like “out of date” rather than “missing.”

Cause 2: Homebrew Ruby and system Ruby fighting each other. If you installed Ruby through Homebrew at some point (a lot of Flutter setup guides tell you to), and your $PATH picks up Homebrew’s Ruby first, your gems get installed in a different location than where Flutter or Xcode expects to find CocoaPods. So you can have CocoaPods “installed” twice, with the version Flutter actually sees being the older one.

Cause 3: The CocoaPods master spec repo confusion. CocoaPods has moved fully toward the trunk-based CDN for specs, and the old master repo path is mostly deprecated now. If your local CocoaPods config still references the old repo somehow, version checks behave unpredictably even after you’ve technically updated. Not super common, but it happens on machines that have been through a lot of CocoaPods installs/reinstalls over the years.

Cause 4 — and this is the one nobody checks first: Xcode Command Line Tools getting reset or partially updated during the macOS upgrade. CocoaPods relies on CLT being properly linked. After a Sequoia upgrade, I’ve seen CLT report as installed while actually missing pieces CocoaPods needs to compile native pods, which surfaces as version-check failures that have nothing to do with the version number itself.

Where People Run Into This

• Fresh macOS Sequoia upgrade, existing Flutter project — by far the most common case. Everything worked fine on Sonoma, then stopped after the OS update.
• M1/M2/M3 Macs specifically — arm64 architecture adds another layer where pod install can fail or behave like a version mismatch even when CocoaPods itself is current.
• Switching between rbenv, rvm, and system Ruby — anyone who’s experimented with Ruby version managers tends to get the messiest version of this problem, because there are now three places CocoaPods could theoretically live.
• CI machines and shared build servers — less personal-laptop-specific, but the same root causes apply, just harder to fix remotely.

Step-by-Step Fix

Step 1: Confirm what version you’re actually running

pod --version
ruby -v
which ruby
which pod

Run all four. The which commands matter more than people expect — they tell you exactly which Ruby and which CocoaPods binary your shell is picking up, which is half the battle here.

Step 2: Update CocoaPods properly

If you installed it originally through the system Ruby:

sudo gem install cocoapods

If you’re on Homebrew Ruby:

brew upgrade cocoapods

Don’t run both unless you genuinely know you need to — that’s how you end up with two competing installs.

Step 3: Clear the CocoaPods cache and repo

pod repo update

This can take a while the first time. If it hangs for more than a few minutes with no output, that’s usually a network/CDN issue, not your machine — worth checking your connection before assuming you broke something.

Step 4: Clean the Flutter iOS build artifacts

flutter clean
cd ios
rm -rf Pods Podfile.lock
cd ..
flutter pub get
cd ios && pod install

This step fixes more cases than people expect, because stale Podfile.lock files reference the old CocoaPods resolution and that’s part of what triggers the warning even after an update.

Step 5: Re-link Xcode Command Line Tools if Steps 1–4 didn’t fix it

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcode-select --install

If the install command says CLT is already installed, that’s not necessarily true in practice. Sometimes you need to fully remove and reinstall:

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

What Actually Worked For Me

I’ll be honest, my first instinct was to just reinstall CocoaPods entirely, full uninstall and fresh gem install. Didn’t work. Version number still showed as outdated to Flutter even though pod --version reported the current release in the terminal.

Spent a chunk of time convinced I’d somehow corrupted my gem path. Tried rbenv, tried switching back to system Ruby, tried clearing ~/.cocoapods entirely. None of it moved the needle, which was genuinely annoying because every guide I found said one of those should’ve fixed it.

What actually did it — and I only found this because a coworker mentioned offhand that he’d had the exact same thing after his own Sequoia upgrade — was the Command Line Tools reset. CLT looked installed in System Settings, reported as installed via xcode-select -p, but the actual toolchain CocoaPods needed to compile certain pods wasn’t fully there. Forcing a full CLT reinstall (the rm -rf version, not just the install command) is what cleared it. Not 100% sure why CLT silently half-breaks like that during an OS upgrade, but it’s apparently common enough that it wasn’t just my machine being weird.

Advanced Fixes and Edge Cases

Check your gem environment directly if version confusion persists:

gem environment
gem list cocoapods

This shows every location Ruby is checking for gems. If CocoaPods shows up in two different gem paths with two different versions, that’s your actual problem — not the OS, not Flutter, just a path conflict that’s been quietly sitting there for a while.

For Apple Silicon specifically, if pod install fails after the version issue is technically resolved, check whether you’re running your terminal under Rosetta. Some older Flutter project setups still have remnants of x86_64-specific configuration in the Podfile, and that combination with native arm64 CocoaPods can throw errors that look related but aren’t really the same root cause.

If you’re on a CI runner, pin your CocoaPods version explicitly in your build script rather than relying on whatever’s pre-installed on the runner image. macOS image providers update their base images on their own schedule, and an unannounced CocoaPods bump (or Ruby bump) on the runner side will break builds with zero warning, usually right when you’re not looking.

Prevention Tips

• Pick one Ruby (system or Homebrew) for CocoaPods and stick with it. Mixing them is the single biggest source of repeat issues here.
• After any macOS major version upgrade, run pod --version and xcode-select -p before you start a Flutter build session, not after something breaks.
• Don’t run sudo gem install cocoapods and brew upgrade cocoapods in the same setup — pick a lane.
• Keep a note of your working ruby -v and pod --version output somewhere, so after an OS upgrade you can quickly compare what changed.

FAQ

Do I need to update CocoaPods every time macOS updates?
Not always, but check anyway. Sometimes nothing breaks. Sometimes everything breaks. Your mileage may vary depending on how your Ruby setup is configured.

Is this a Flutter bug that will get patched?
No — the version check itself is working as intended. The underlying CocoaPods/Ruby state is what’s broken, and that’s largely an Apple/Ruby-ecosystem issue, not something Flutter can fix on their end.

Will switching to Homebrew Ruby fix this permanently?
It can help, but it’s not a guarantee. Plenty of people run Homebrew Ruby and still hit this after a major macOS upgrade.

Why does pod install work but Flutter still shows the warning?
Usually a path mismatch — your terminal’s active shell session is picking up a different CocoaPods binary than whatever Flutter’s tooling checks against. Run which pod in the exact terminal you’re using to build.

Does this affect Android builds too?
No, this is iOS/macOS-specific since CocoaPods only matters for the iOS build pipeline.

Editor’s Opinion

yeah this one’s annoying because the error message makes it sound like a two-second fix and most of the time it isn’t. if you just updated to Sequoia and your Flutter iOS build broke, check Command Line Tools before anything else — that’s the one that got me and it’s not even on most people’s checklist. CocoaPods itself is usually fine, it’s everything underneath it that gets messy after an OS update.