How to Use CocoaPods Instead of SPM with Capacitor¶
Capacitor 8 made Swift Package Manager (SPM) the default dependency manager for new iOS projects. While SPM is the future of iOS dependency management, it still has some rough edges that can block real-world projects. In those cases, CocoaPods remains a solid alternative. This post covers when you might want to stick with CocoaPods and how to set it up.
Why SPM Is the Default¶
When the Ionic team announced Capacitor 8, one of the headline changes was adopting SPM as the default package manager for iOS. This aligns with the broader iOS ecosystem trend: CocoaPods entered maintenance mode in August 2024, and its Specs repository will become read-only in December 2026. Apple has been pushing SPM as the official replacement, and most first-party frameworks already ship with SPM support.
For many projects, SPM works well out of the box. But SPM is still maturing, and there are cases where it falls short.
When CocoaPods Is the Better Choice¶
Here are two real-world examples where SPM limitations can cause issues in Capacitor projects:
Package Identity Collisions¶
SPM determines a package's identity based on its path or URL. When Capacitor generates the Package.swift for your project, this can lead to identity collisions where two unrelated packages end up with the same identity. Depending on the Xcode version, this may cause warnings or hard build errors.
See capawesome-team/capacitor-firebase#959 for a concrete example.
Missing Support for Package Traits¶
Swift 6.1 introduced Package Traits (SE-0450), which allow package authors to define optional, toggleable dependencies. A practical example: the Firebase Analytics SDK offers a variant with IDFA/Ad ID collection support and one without. CocoaPods handled this cleanly via subspecs, and SPM package traits are the intended replacement.
However, since Capacitor generates the Package.swift on behalf of the developer, there is currently no way to pass traits to plugin dependencies. Until Capacitor adds support for this (tracked in ionic-team/capacitor#8335), projects that need to toggle SDK features like IDFA support are better off using CocoaPods.
Other Considerations¶
Beyond these specific issues, there are a few more reasons to prefer CocoaPods:
- Third-party plugin support: Not all Capacitor plugins have added SPM support yet. If a plugin you depend on only ships a
.podspec, you need CocoaPods. - Mixed Objective-C/Swift plugins: SPM does not allow mixing Objective-C and Swift in the same target. Plugins that rely on this pattern require CocoaPods.
- You cannot mix SPM and CocoaPods: This is a hard constraint. If even one of your dependencies requires CocoaPods, your entire project needs to use CocoaPods.
Setting Up CocoaPods¶
Using CocoaPods with Capacitor 8 is straightforward. When adding the iOS platform to your project, pass the --packagemanager flag with the value cocoapods:
That's it. Capacitor will generate the iOS project with a Podfile instead of a Package.swift, and all plugin dependencies will be resolved through CocoaPods.
If you already have an iOS project using SPM and want to switch to CocoaPods, you'll need to remove the existing iOS project first and re-add it:
Make sure to back up any custom native code before removing the platform.
Try Capawesome Cloud¶
If you're building Capacitor apps, Capawesome Cloud can help you ship faster with cloud-based native builds, over-the-air updates, and more.
Conclusion¶
SPM is the direction Apple and the Capacitor team are heading, and it's the right default for most new projects. But it's still evolving, and edge cases like package identity collisions and missing package trait support can be real blockers. When you hit one of these issues, CocoaPods is a proven fallback that works reliably with Capacitor 8.
If you have questions, feel free to join the Capawesome Discord server. To stay up to date with the latest news, subscribe to the Capawesome newsletter.