What are CocoaPods in Flutter?
CocoaPods in Flutter is the native dependency manager for iOS and macOS. It is responsible for downloading and linking iOS frameworks required by Flutter plugins such as Firebase, camera, or maps.
Whenever a Flutter plugin contains native iOS code, CocoaPods is used to integrate it into the app. In practice, CocoaPods has been a required part of Flutter iOS development for years, even though Flutter usually runs it automatically.
Why does it matter in Flutter app development?
If CocoaPods is misconfigured:
- iOS builds fail
- plugins do not compile
flutter doctor reports errors
Most Flutter iOS setup issues come from CocoaPods, not Flutter itself. Understanding this layer saves a lot of debugging time.
How does it work?
When you run flutter pub get or build an iOS app, Flutter generates native files inside the ios/ directory.
CocoaPods reads the Podfile, resolves native dependencies, and installs them into an Xcode workspace (Runner.xcworkspace). Flutter triggers CocoaPods behind the scenes, but CocoaPods must be correctly installed and configured on macOS.
CocoaPods deprecation and the move to Swift Package Manager
Starting with Xcode 26, CocoaPods is officially deprecated by Apple in favor of Swift Package Manager (SPM).
This means:
- CocoaPods will continue to work for existing projects.
- Apple no longer recommends CocoaPods for new native iOS development.
- Flutter is gradually moving toward native SPM integration.
At the time of writing, most Flutter plugins still rely on CocoaPods, so CocoaPods remains necessary for many projects. However, developers should expect SPM to become the default dependency system for Flutter iOS apps in the coming years.
How to install CocoaPods for Flutter (important warning)
Do not use the system Ruby shipped with macOS. It is outdated and protected by the system, which leads to permission errors and broken setups.
Recommended approach
- Install Ruby via Homebrew or a version manager (
rbenv / chruby). - Then install CocoaPods without relying on system Ruby
Example (Homebrew-based setup)
brew install ruby
gem install cocoapods
Avoid using sudo gem install cocoapods whenever possible.
Key characteristics
CocoaPods in Flutter:
- Manages native iOS dependencies for plugins.
- Generates and updates the Xcode workspace.
- Locks dependency versions using
Podfile.lock. - Runs automatically during Flutter iOS builds.
Common mistakes
Typical issues include:
- Opening
Runner.xcodeproj instead of Runner.xcworkspace. - Using system Ruby and breaking gem permissions.
- CocoaPods installed but not available in
PATH. - Ignoring
Podfile.lock in version control. - Architecture conflicts on Apple Silicon Macs.
Troubleshooting: the universal fix
When iOS builds fail with unclear dependency errors, use this sequence:
cd ios
rm -rf Pods
rm Podfile.lock
pod install
cd ..
This resolves most CocoaPods-related issues caused by inconsistent native dependencies.
Apple Silicon (M1/M2/M3) note
On newer Macs, rare projects may still require Rosetta for older native libraries.
In such cases, running pod install under x86_64 can help, though this is increasingly uncommon in modern Flutter projects.
Best practices
To keep CocoaPods stable:
- Commit
Podfile.lock to Git. - Keep CocoaPods and Xcode updated.
- Let Flutter manage the
Podfile unless necessary. - Always build and archive from the workspace, not the project file.
When to use CocoaPods in Flutter?
You use CocoaPods whenever:
- Your Flutter app targets iOS or macOS.
- You rely on plugins with native iOS code.
- You build or release apps to the App Store.
