Embracing Swift Package Manager: A Comprehensive Migration Guide for Flutter Developers

Overview

Starting with Flutter 3.44, Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps, marking the end of CocoaPods for new projects. CocoaPods is now in maintenance mode, and its registry will become read-only on December 2, 2026. While existing builds continue to work, no new pod versions or additions to the trunk will occur after that date. This guide helps you navigate the transition, whether you’re an app developer or a plugin maintainer.

Prerequisites

• Flutter SDK version 3.44 or later installed.
• An existing Flutter project targeting iOS and/or macOS.
• Basic familiarity with pubspec.yaml and Xcode project settings.
• For plugin developers: knowledge of Swift package structures and Package.swift format.

Step-by-Step Migration Guide

For App Developers

The Flutter CLI automates the migration. When you run or build your app, it automatically updates your Xcode project to use SwiftPM. No manual steps are required for most projects.

1. Update your Flutter SDK to version 3.44 or newer (e.g., flutter upgrade).
2. Build or run your app using flutter run or flutter build ios. The CLI detects that SwiftPM should be used and converts your Xcode project accordingly.
3. Check for warnings: If any plugins in your pubspec.yaml haven’t migrated to SwiftPM, Flutter prints a warning listing them. It temporarily falls back to CocoaPods for those dependencies.

Handling unsupported plugins: If a plugin you rely on hasn’t adopted SwiftPM, you have two options:

• Contact the plugin’s maintainer to request SwiftPM support, or
• Find an alternative package that already supports SwiftPM.

Opting out temporarily: If SwiftPM causes critical issues, you can disable it per project. Open your pubspec.yaml and under the flutter section, set enable-swift-package-manager to false:

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

If you opt out, please file a bug report on the Flutter GitHub repository with error details, plugin list, and Xcode project files.

For Plugin Developers

If you maintain an iOS or macOS plugin, you must add SwiftPM support. Currently, 61% of the top 100 iOS plugins have migrated. Without SwiftPM support, your package receives a lower pub.dev score, and app developers may be blocked after the CocoaPods deadline.

1. Create a Package.swift file in the root of your plugin’s iOS folder (ios/).
2. Restructure source files to follow SwiftPM conventions: place Swift and Objective-C sources under Sources/<PackageName>/.
3. Declare your target in Package.swift with the correct platform and dependencies. For example:

// swift-tools-version:5.7
import PackageDescription

let package = Package(
    name: "MyPlugin",
    platforms: [
        .iOS(.v12),
        .macOS(.v10_14)
    ],
    products: [
        .library(
            name: "MyPlugin",
            targets: ["MyPlugin"]
        )
    ],
    dependencies: [
        // Add FlutterFramework as a dependency
        .package(url: "https://github.com/flutter/engine", from: "3.44.0")
    ],
    targets: [
        .target(
            name: "MyPlugin",
            dependencies: [
                .product(name: "FlutterFramework", package: "engine")
            ],
            path: "Sources/MyPlugin"
        )
    ]
)

Important: If you participated in the 2025 pilot and already migrated, you must now add FlutterFramework as an explicit dependency (as shown above). This step ensures compatibility with Flutter 3.44+.

Refer to the official Flutter migration documentation for further details.

Common Mistakes and Troubleshooting

1. Forgetting to update the Flutter SDK

If you run Flutter 3.43 or earlier, SwiftPM support is not enabled by default. Ensure you’ve upgraded to 3.44+.

2. Misspelled pubspec.yaml config key

Use enable-swift-package-manager (with hyphens) under flutter: config:. Typographical errors will be silently ignored.

3. Plugin source files not moved to Sources/

SwiftPM expects sources in the Sources directory. Leaving them in the root will cause build failures.

4. Missing FlutterFramework dependency

Without it, your plugin might compile but fail at runtime. Double-check your Package.swift dependencies.

5. Ignoring warning messages during build

If you see warnings about unsupported plugins, they are not fatal but indicate future breakage. Plan to replace or update those dependencies.

Summary

Flutter’s shift to Swift Package Manager streamlines iOS/macOS development by eliminating Ruby and CocoaPods. App developers can rely on automatic CLI migration, with a fallback for unadapted plugins. Plugin maintainers must add SwiftPM support, including the FlutterFramework dependency, to avoid declining pub.dev scores and future breakage. Act now to ensure your Flutter projects remain compatible beyond 2026.