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

Introduction

With the upcoming Flutter stable release (version 3.44), Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps. This shift means you no longer need to deal with Ruby or CocoaPods installations. CocoaPods is officially in maintenance mode and its registry will become read-only on December 2, 2026. While existing builds will continue to work, no new versions or pods will be added after that date. To keep your apps receiving dependency updates and to access the Swift package ecosystem, Flutter is transitioning to Apple's supported solution: Swift Package Manager.

This guide will walk you through the migration process, whether you are an app developer or a plugin developer. Follow the steps carefully to ensure a smooth transition.

What You Need

• Flutter SDK version 3.44 or later (stable channel)
• An existing Flutter project targeting iOS or macOS
• Xcode (latest version recommended)
• Basic familiarity with pubspec.yaml and terminal commands
• For plugin developers: a Flutter plugin with iOS/macOS support

Step-by-Step Migration Guide

Step 1: Update Flutter to the Latest Stable Version

First, ensure you have Flutter 3.44 or newer installed. Run the following command in your terminal:

flutter upgrade

After upgrading, verify your version:

flutter --version

Look for the version number; if it’s below 3.44, run flutter channel stable and then flutter upgrade again.

Step 2: Build or Run Your App Normally

The Flutter CLI handles most of the migration automatically. Simply run your app as you usually would:

flutter run

or build for iOS/macOS:

flutter build ios

When you execute these commands, Flutter will automatically update your Xcode project to use Swift Package Manager. There is no manual action required at this stage for app developers.

Step 3: Check for Plugin Warnings

During the build, Flutter checks whether all your dependencies (plugins) have adopted Swift Package Manager. If any plugin hasn’t migrated yet, you’ll see a warning listing the unsupported packages. For example:

Warning: The following plugins do not support Swift Package Manager: [plugin_name]

In such cases, Flutter temporarily falls back to CocoaPods for those plugins. However, since CocoaPods support will eventually be removed entirely, you should take action:

• Contact the plugin maintainer and request SwiftPM support.
• Search for alternative packages that already support SwiftPM.
• If the plugin is critical and unmaintained, consider migrating it yourself (see plugin developer steps below).

Step 4: Temporarily Disable SwiftPM (If Needed)

If the migration causes a breaking issue in your project, you can opt out temporarily. Open your pubspec.yaml file and locate the flutter section. Add or modify the config block as follows:

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

After making this change, run flutter clean and then flutter pub get to revert to CocoaPods. Important: This is a temporary safety net. Please report any breaking issues to the Flutter team using the Flutter GitHub issue template. Include error details, list of plugins and versions, and copies of your Xcode project files. This helps the team fix the problem before CocoaPods is completely removed.

Step 5: Plugin Developers – Add SwiftPM Support

If you maintain a Flutter plugin for iOS or macOS, you must add Swift Package Manager support if you haven’t already. As of now, about 61% of the top 100 iOS plugins have migrated. The remaining plugins receive lower pub.dev scores, encouraging adoption. Follow these sub-steps:

5a. Create a Package.swift File

In the root of your plugin’s iOS or macOS directory (usually ios/ or macos/), create a file named Package.swift. This file defines your Swift package and its dependencies.

5b. Move Source Files to Match Standard Structure

Swift packages expect source files to be in a specific layout. Typically, place your Swift source files in a Sources/ subfolder. For example:

ios/
  Package.swift
  Sources/
    YourPluginName/
      YourPlugin.swift
      ...

If your plugin already had a standard structure from the 2025 pilot, you may need to adjust folder names or paths.

5c. Add FlutterFramework Dependency

If you migrated during the 2025 pilot, you must now complete an additional step: add FlutterFramework as a dependency in your Package.swift file. This ensures your plugin can access Flutter APIs. Your Package.swift should include:

// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: "YourPluginName",
    platforms: [
        .iOS(.v12),
        .macOS(.v10_14)
    ],
    products: [
        .library(
            name: "YourPluginName",
            targets: ["YourPluginName"]
        )
    ],
    dependencies: [
        .package(url: "https://github.com/flutter/flutter.git", from: "3.22.0")  // Example; use actual Flutter package
    ],
    targets: [
        .target(
            name: "YourPluginName",
            dependencies: [
                .product(name: "Flutter", package: "flutter")
            ]
        )
    ]
)

Adjust the Flutter package URL and version to match the latest Flutter release.

5d. Test and Publish

After making changes, test your plugin using the flutter test command and verify it builds for both iOS and macOS. Then publish an updated version to pub.dev. Your pub.dev score will improve once the package supports SwiftPM.

Tips

• Report Issues Promptly: If SwiftPM causes build failures, file a bug report with detailed logs. The Flutter team is actively working on resolving migration issues.
• Check Plugin Scores: When choosing plugins, prefer those with SwiftPM support. They have higher pub.dev scores and better future compatibility.
• Keep CocoaPods as Fallback: Even after migration, you can temporarily revert to CocoaPods using the enable-swift-package-manager: false flag. Use this only if absolutely necessary.
• Update Your Docs: If you are a plugin developer, update your plugin’s README to reflect the new SwiftPM support and any migration steps for users.
• Monitor the Community: Follow Flutter’s official blog and GitHub discussions for updates on the migration timeline and additional tooling.

With these steps, you’ll be ready for the future of Flutter dependency management. Swift Package Manager brings tighter integration with Xcode and better performance, making your development workflow smoother.