Migrating Flutter iOS and macOS Projects from CocoaPods to Swift Package Manager: A Complete Guide

By • min read

Overview

With the upcoming Flutter 3.44 stable release, the default dependency manager for iOS and macOS apps is shifting from CocoaPods to Swift Package Manager (SwiftPM). CocoaPods has entered maintenance mode, and its registry will become read-only on December 2, 2026. After that date, no new pods or versions will be added, though existing builds will remain functional. To ensure your Flutter apps continue to receive dependency updates and to gain access to the broader Swift package ecosystem, migrating to SwiftPM is now essential.

This guide provides a detailed walkthrough for both app developers and plugin developers, covering prerequisites, step-by-step migration instructions, common pitfalls, and how to temporarily opt out if issues arise. By the end, you’ll be ready to embrace SwiftPM and leave CocoaPods behind.

Prerequisites

Before you begin, ensure your environment meets these requirements:

• Flutter SDK 3.44 or later – Download from the official Flutter website or update via flutter upgrade.
• Xcode 15.0 or later – Required for SwiftPM support; older versions may not work.
• macOS – iOS and macOS development inherently requires a Mac.
• Basic knowledge of Flutter project structure and familiarity with pubspec.yaml.
• Optional: For plugin developers, familiarity with Swift and Xcode project files will help.

Step-by-Step Instructions

For App Developers

1. Update your Flutter SDK – Run flutter upgrade in your terminal to ensure you’re on version 3.44 or higher.
2. Run or build your app as usual – When you execute flutter run (for iOS or macOS) or flutter build ios/flutter build macos, the CLI automatically migrates your Xcode project to use Swift Package Manager. The migration happens in the background—no manual steps required.
3. Check for plugin warnings – If any of your dependencies (plugins) haven’t adopted SwiftPM yet, Flutter will print a clear warning listing those plugins. The system will fall back to CocoaPods for those unsupported plugins temporarily. For example:

   Warning: Plugin 'some_plugin' does not support Swift Package Manager. Falling back to CocoaPods.

4. Handle unsupported plugins – If a plugin breaks your build because it hasn’t migrated, file an issue on the plugin’s repository requesting SwiftPM support, or search for an alternative package that already supports SwiftPM.
5. Opt out temporarily (if needed) – If SwiftPM causes a breaking issue (e.g., dependency resolution errors), you can disable it for your project. Open your pubspec.yaml and add the following under the flutter section:

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

   After making this change, run flutter clean and then rebuild. If you opt out, please report the issue to the Flutter team using the Flutter GitHub bug template—include error details, a list of your plugins and versions, and copies of your Xcode project files.

For Plugin Developers

1. Add Swift Package Manager support – If you haven’t already, create a Package.swift file in the root of your plugin’s iOS/macOS directory. Follow the standard Swift package structure:

   // swift-tools-version:5.9
   import PackageDescription
   
   let package = Package(
       name: "YourPlugin",
       platforms: [
           .iOS(.v12),
           .macOS(.v10_15)
       ],
       products: [
           .library(
               name: "YourPlugin",
               targets: ["YourPlugin"])
       ],
       dependencies: [
           .package(url: "https://github.com/flutter/flutter.git", from: "3.44.0")
       ],
       targets: [
           .target(
               name: "YourPlugin",
               dependencies: [
                   .product(name: "FlutterFramework", package: "flutter")
               ],
               path: "ios/Classes"
           )
       ]
   )

2. Move source files – Place your Swift/ObjC source files inside a Sources directory (or specify a custom path in Package.swift as shown above). Organize them to match the SwiftPM layout.
3. Add FlutterFramework dependency – If you already migrated during the 2025 pilot, note the new requirement: you must add FlutterFramework as an explicit dependency in your Package.swift. The example above includes it under the target’s dependencies. Without this, the plugin won’t link correctly.
4. Update pubspec.yaml – Ensure your plugin’s pubspec.yaml references the correct paths and includes any necessary version constraints.
5. Test your plugin – Run a sample Flutter app that uses your plugin to verify everything works. Publish an updated version to pub.dev.

Common Mistakes

• Forgetting to update Flutter SDK – Migrating before upgrading to 3.44 may cause unexpected behavior. Always run flutter upgrade first.
• Ignoring plugin warnings – If you see a warning about unsupported plugins, don’t ignore it. Although a fallback exists, it’s temporary. Contact plugin maintainers or replace the plugin.
• Missing FlutterFramework dependency (plugin devs) – Existing package files from earlier pilots are missing this line. Without it, the app will fail to link at runtime. Double-check your Package.swift for .product(name: "FlutterFramework", package: "flutter").
• Incorrect source path – If your source files are not in the expected structure, SwiftPM cannot find them. Use the path parameter in your target definition to point to the correct directory.
• Not cleaning the project – After changing settings (especially the opt-out flag), run flutter clean to clear caches and avoid stale builds.

Summary

Flutter 3.44 marks the end of the CocoaPods era for iOS/macOS dependency management. App developers benefit from automatic migration via the CLI, with a temporary fallback for plugins that haven’t updated. Plugin authors must add SwiftPM support—including the new FlutterFramework dependency—to maintain compatibility and pub.dev scores. By following this guide, you can transition smoothly and ensure your Flutter apps remain future-proof.