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

Introduction

Flutter is making a major shift: starting with the upcoming stable release (version 3.44), Swift Package Manager (SwiftPM) will become the default dependency manager for iOS and macOS apps. This means no more wrestling with Ruby installations or CocoaPods just to run your Flutter app on Apple devices. CocoaPods has entered maintenance mode and its registry will be permanently read-only on December 2, 2026. While existing builds will still work, no new versions or pods will be added after that date.

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

To ensure your apps continue receiving dependency updates and to unlock the larger Swift package ecosystem, Flutter is transitioning to Apple's supported solution: Swift Package Manager. This guide walks you through everything you need to know, whether you're an app developer or a plugin author.

What You Need

Flutter SDK version 3.44 or later (stable channel)
Xcode (latest version recommended)
An existing Flutter project targeting iOS or macOS
For plugin developers: a text editor or IDE, familiarity with Swift package structure
Basic understanding of dependency management in Flutter

Step 1: Let the Flutter CLI Handle the Migration (App Developers)

For most app developers, the migration is automatic. When you run or build your iOS or macOS app, the Flutter CLI will update your Xcode project to use Swift Package Manager. There's no manual step required—just use the usual flutter run or flutter build ios commands.

Behind the scenes, Flutter scans your pubspec.yaml for dependencies and converts them to Swift Package Manager equivalents when possible. If all your plugins have already adopted SwiftPM, you're done. The CLI will produce a clean build without any CocoaPods involvement.

Dealing with Unsupported Plugins

If any of your plugins haven't adopted Swift Package Manager yet, Flutter will print a warning listing exactly which dependencies are unsupported. In that case, the framework will temporarily fall back to CocoaPods for those specific plugins. This ensures your build still works now, but be aware: CocoaPods support will eventually be removed entirely.

If a critical plugin breaks your build because it lacks Swift package support, you have two options:

File an issue with the plugin maintainer requesting SwiftPM migration
Search for an alternative package that already supports SwiftPM

Step 2: Temporarily Disable SwiftPM (If Necessary)

If Swift Package Manager causes a breaking issue in your project, you can disable it and return to CocoaPods for now. Open your pubspec.yaml file and locate the flutter section. Add or edit the config block as follows:

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

After making this change, run flutter clean and rebuild. Please note that this is a temporary workaround. CocoaPods will be completely removed in the future, so you should plan to migrate soon. If you opt out, please file a bug report using the Flutter GitHub issue template with these details:

Error details and logs
List of your plugins and versions
Copies of your Xcode project files

This helps the Flutter team resolve issues before CocoaPods is fully deprecated.

Step 3: Migrate Your Plugin (Plugin Developers)

If you maintain an iOS or macOS Flutter plugin, you must add Swift Package Manager support as soon as possible. Currently, about 61% of the top 100 iOS plugins have migrated. The remaining 39% need to update so app developers aren't stuck relying on a deprecated tool. To encourage adoption, packages without SwiftPM support now receive lower pub.dev scores until they migrate.

How to Add Swift Package Manager Support

Create a Package.swift file in your plugin's root directory. This file defines your Swift package, its targets, and dependencies.
Move your source files to match the standard Swift package structure. Typically, place shared code under Sources/ and tests under Tests/.
If you migrated during the 2025 pilot, you need to complete one new step: add FlutterFramework as a dependency in your Package.swift file. This ensures your Swift package can link against the Flutter runtime.
Test your plugin by running a sample Flutter app that depends on it. Ensure the build uses SwiftPM and doesn't fall back to CocoaPods.

For detailed instructions, refer to the official Flutter migration docs for plugin developers. They contain the exact syntax for Package.swift and best practices for organizing your code.

Tips for a Smooth Transition

Communicate changes: If you're a plugin maintainer, update your README and CHANGELOG to announce SwiftPM support. This helps app developers know they can rely on your package.
Test both iOS and macOS targets – Swift Package Manager behavior may differ slightly between the two platforms.
Keep an eye on CocoaPods sunset: Mark December 2, 2026 on your calendar. After that date, no new pods will be accepted, so ensure your project is fully migrated before then.
If you encounter issues with a specific plugin that hasn't migrated, try using the git dependency in pubspec.yaml to point directly to the plugin's repository if they have a development branch with SwiftPM support.
Check pub.dev scores – if your plugin's score drops due to lack of SwiftPM, prioritize migration to maintain visibility and trust.
Join the Flutter community on GitHub and Discord to discuss migration challenges and share solutions.

By following these steps, you can smoothly transition from CocoaPods to Swift Package Manager, ensuring your Flutter projects remain up-to-date and compatible with the future of Apple ecosystem development.

Tags: