Migrating from CocoaPods to Swift Package Manager in Flutter: A Step-by-Step Guide

By ✦ min read

Introduction

Flutter’s next stable release, version 3.44, marks a major shift in iOS and macOS dependency management. Swift Package Manager (SwiftPM) becomes the default tool, replacing CocoaPods. This change eliminates the need to juggle Ruby installations or CocoaPods setups. CocoaPods will enter maintenance mode, and its registry becomes read-only on December 2, 2026. While existing builds still work, no new updates or packages will be added after that date. To keep your apps receiving dependency updates and to tap into the Swift package ecosystem, Flutter is transitioning to Apple’s supported solution. This guide walks you through the migration process for both app developers and plugin authors.

Migrating from CocoaPods to Swift Package Manager in Flutter: A Step-by-Step Guide

What You Need

Flutter 3.44 or later installed
An existing Flutter project with iOS or macOS support
Xcode (latest version recommended)
Basic familiarity with the pubspec.yaml file
(For plugin developers) A Flutter plugin with iOS/macOS code

Step-by-Step Migration Process

For App Developers

Step 1: Update Flutter to version 3.44 or later
Run flutter upgrade in your terminal to fetch the latest stable Flutter version. Confirm with flutter --version that you’re on 3.44+.

Step 2: Run or build your iOS/macOS app
Use flutter run or flutter build ios (or macOS equivalents). The Flutter CLI automatically updates your Xcode project to use Swift Package Manager. No manual intervention is required for most projects. For detailed reference, consult the Flutter migration docs for app developers.

Step 3: Review warnings about unsupported plugins
After running, Flutter may print a warning listing dependencies that haven’t adopted SwiftPM yet. If your app relies on such plugins, Flutter temporarily falls back to CocoaPods for those specific packages. This fallback is a bridge until all plugins migrate. If a plugin’s lack of support breaks your build, file an issue with its maintainer or find an alternative package.

Step 4: (Optional) Disable SwiftPM if you encounter issues
If SwiftPM causes a breaking problem, you can temporarily revert to CocoaPods. Open your pubspec.yaml and locate the flutter section. Add the following configuration:

flutter:
  config:
    enable-swift-package-manager: false

After disabling, please file a bug report using the Flutter GitHub issue template. Include error details, a list of your plugins and versions, and copies of your Xcode project files. This helps the Flutter team resolve issues before CocoaPods support is fully removed.

For Plugin Developers

Step 5: Add Swift Package Manager support to your plugin
If you haven’t already, you must support SwiftPM. Currently, 61% of the top 100 iOS plugins have migrated. The remaining plugins need to adopt SwiftPM to avoid relying on deprecated CocoaPods. Packages without SwiftPM support now receive lower scores on pub.dev, pressuring them to migrate.

Step 6: Create a Package.swift file and restructure your source
Add a Package.swift file to your plugin’s root directory. Move your iOS/macOS source files to match the standard Swift package structure (e.g., Sources/YourPlugin). For detailed instructions, see the Flutter migration docs for plugin developers.

Step 7: Add FlutterFramework as a dependency if you migrated earlier
If you already migrated your plugin during the 2025 pilot, you must complete one new step: add FlutterFramework as a dependency in your Package.swift file. This ensures compatibility with the latest Flutter changes.

Tips for a Smooth Transition

Test early: Run your app on both iOS and macOS to catch integration issues before the CocoaPods removal deadline.
Monitor warnings: Keep an eye on Flutter’s CLI output for any plugin-related messages.
Migrate proactively: If you maintain plugins, prioritize SwiftPM support to avoid pub.dev score penalties.
Use the fallback wisely: The temporary CocoaPods fallback is a safety net, but don’t rely on it long-term.
Report bugs: Use the Flutter GitHub issue template to help improve the migration experience.
Check official docs: Bookmark the Flutter migration documentation for the latest updates.

By following this guide, you’ll ensure your Flutter apps and plugins are ready for the Swift Package Manager era.

Tags: