Seamlessly Migrate from CocoaPods to Swift Package Manager in Flutter

Introduction

Flutter's upcoming stable release (3.44) marks a major shift: Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps, replacing CocoaPods. No more Ruby headaches or manual CocoaPods installations. CocoaPods is entering maintenance mode, with its registry becoming read-only on December 2, 2026. To keep receiving dependency updates and tap into the Swift package ecosystem, Flutter is adopting Apple's native solution. This guide walks you through the migration for both app developers and plugin developers, ensuring a smooth transition.

What You Need

• Flutter SDK version 3.44 or newer (stable channel)
• An existing Flutter project targeting iOS and/or macOS
• Xcode 15.0 or later (for SwiftPM compatibility)
• Basic familiarity with your project's pubspec.yaml file
• For plugin developers: access to the plugin's source code and a GitHub account for issues

Step-by-Step Migration Guide

For App Developers

Step 1: Update Your Flutter SDK

Ensure you are using Flutter 3.44 or newer. Run flutter upgrade in your terminal. Verify with flutter --version.

Step 2: Let the Flutter CLI Handle the Migration

Simply run or build your app as usual: flutter run or flutter build ios / flutter build macos. The Flutter CLI automatically updates your Xcode project to use Swift Package Manager. No manual steps are required for most projects.

Step 3: Check for Unsupported Plugins

During the build, Flutter will print a warning list of any plugins that have not yet adopted SwiftPM. These plugins will temporarily fall back to CocoaPods, but this fallback will be removed in future Flutter versions. If a plugin breaks your build, file an issue with the plugin's maintainer requesting Swift package support, or find an alternative package.

Step 4: (Optional) Temporarily Disable SwiftPM If Issues Arise

If SwiftPM causes a breaking issue in your project, you can opt out temporarily. Open your pubspec.yaml file, locate the flutter section, and 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 completely removed.

For Plugin Developers

Step 1: Add Swift Package Manager Support

If you haven't already, add a Package.swift file to your plugin's iOS or macOS source tree. Move your source files to match the standard Swift package structure (e.g., Sources/YourPluginName/). If you migrated during the 2025 pilot, you must complete an additional step (see Step 2).

Step 2: Add FlutterFramework as a Dependency

In your Package.swift file, include a dependency on FlutterFramework. For example:

dependencies: [
    .package(url: "https://github.com/flutter/flutter", from: "3.44.0")
],
targets: [
    .target(name: "YourPluginName", dependencies: ["FlutterFramework"])
]

This step is mandatory for all plugins. Refer to the Flutter migration docs for the exact syntax and requirements.

Step 3: Verify Migration and Update pub.dev Score

Once your plugin supports SwiftPM, its pub.dev score will improve. Currently, 61% of the top 100 iOS plugins have migrated. Plugins without SwiftPM support receive lower scores, so complete this migration to stay competitive and avoid breaking app developer builds.

Tips for a Successful Migration

• Test on a copy: Before migrating your production project, run tests on a clone or branch to identify any plugin incompatibilities.
• Monitor warnings: Pay attention to Flutter's build warnings about unsupported plugins. They list exact package names.
• Communicate with maintainers: If you encounter a broken plugin, file a polite issue on the plugin's repository. Many maintainers are still migrating.
• Keep Ruby/CocoaPods installed temporarily: Until all your dependencies have migrated, you may still need CocoaPods for fallback. Don't uninstall it yet.
• Stay updated: Follow Flutter's official changelog and migration guides. The December 2026 deadline is approaching, so plan accordingly.
• Consider alternatives: If a plugin fails to migrate in time, look for alternative packages that already support SwiftPM.
• Contribute: If you're a plugin developer, help the community by migrating your plugin early. Your users will thank you.