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

Introduction

Starting with Flutter 3.44, Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps, replacing CocoaPods. This shift eliminates the need for Ruby and manual CocoaPods installations. CocoaPods is now in maintenance mode, and its registry will become read-only on December 2, 2026. While existing builds remain functional, new updates and pods will cease. To ensure your apps continue receiving dependency updates and to tap into Apple’s robust Swift package ecosystem, Flutter is moving to SwiftPM. This guide walks you through the migration process for both app developers and plugin developers.

What You Need

• Flutter SDK version 3.44 or later (stable channel)
• Xcode (latest version recommended)
• An existing Flutter project with iOS or macOS support
• For plugin developers: Familiarity with Swift package structure and access to your plugin’s source code

Step-by-Step Migration Guide

For App Developers

1. Update Flutter to 3.44 Or Later
   Run flutter upgrade in your terminal to get the latest stable version. This ensures the CLI can handle the automatic migration.
2. Build Or Run Your iOS/MacOS App
   Execute flutter run or flutter build ios. The Flutter CLI automatically updates your Xcode project to use Swift Package Manager. No manual intervention is required for the initial migration.
3. Check For Warnings About Unsupported Plugins
   After running, if any plugins haven't adopted SwiftPM yet, Flutter prints a warning listing those dependencies. The CLI temporarily falls back to CocoaPods for such plugins. Note that CocoaPods support will be removed entirely in the future, so plan to replace or migrate these plugins.
4. If Migration Breaks Your Build, Temporarily Disable SwiftPM
   Open your pubspec.yaml file. Under the flutter section, add the following configuration block:

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

   This reverts to CocoaPods for the entire project. If you need to disable SwiftPM, please file a bug report on the Flutter GitHub issue tracker. Include error details, a list of your plugins and versions, and copies of your Xcode project files to help resolve the issue before CocoaPods support is dropped.
5. Verify Successful Migration
   Open your Xcode project and check that Swift packages are listed under the project navigator. Run a full build and test on a device or simulator to ensure no dependency issues remain.

For Plugin Developers

1. Add Swift Package Manager Support If Not Already Done
   As of now, 61% of the top 100 iOS plugins have migrated. Plugins without SwiftPM support now receive lower pub.dev scores, encouraging migration. To add support, create a Package.swift file in your plugin’s root directory.
2. Move Source Files To Match Standard Swift Package Structure
   Organize your source files under Sources/YourPluginName/. This aligns with Swift package conventions. Remove any CocoaPods-specific files like .podspec if they are no longer needed.
3. Add FlutterFramework As A Dependency In Package.swift
   If you migrated during the 2025 pilot, you need to add one new step: declare FlutterFramework as a dependency. Your Package.swift should include:

   .package(url: "https://github.com/flutter/flutter.git", from: "3.44.0")

   Then in your target, add "FlutterFramework" as a dependency.
4. Test Your Plugin With A Sample Flutter App
   Create or use an existing Flutter project that depends on your plugin. Run flutter run to ensure the migration works. Check that no warnings appear about CocoaPods fallback.
5. Update Pub.Dev Listing
   Publish a new version of your plugin after migration. Indicate in the changelog that SwiftPM is now supported. This improves your pub.dev score and helps app developers adopt the new dependency manager.

Tips For A Smooth Migration

• Act Quickly: CocoaPods registry becomes read-only on December 2, 2026. Migrate well before this date to avoid last-minute disruptions.
• Fallback Is Temporary: Flutter’s fallback to CocoaPods for non-migrated plugins is only a stopgap. Prioritize replacing or updating any plugins that lack SwiftPM support.
• File Issues For Broken Dependencies: If a plugin breaks your build after migration, contact the maintainer or file an issue requesting SwiftPM support. Consider switching to an alternative package.
• Keep Xcode Updated: SwiftPM relies on Xcode’s SPM integration. Always use the latest Xcode version from Apple.
• Test On Both iOS And macOS: If your app supports both platforms, test migration on each to catch platform-specific issues.
• Use Flutter’s Official Docs: For detailed guidance, refer to the Flutter migration docs.