Navigating the Shift to Swift Package Manager in Flutter: Your Step-by-Step Migration Guide

Introduction

Flutter is officially moving away from CocoaPods. Starting with version 3.44, Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps. This change means no more wrestling with Ruby or installing CocoaPods just to run your project. CocoaPods is now in maintenance mode, and its registry will go read-only on December 2, 2026. To keep getting dependency updates and tap into the Swift package ecosystem, you need to migrate. This guide walks both app developers and plugin authors through the process step by step.

What You Need

• Flutter SDK 3.44 or later
• Xcode installed (recent version)
• An existing Flutter project with iOS/macOS dependencies
• For plugin developers: a GitHub or similar account, access to your plugin repository, and familiarity with Package.swift
• Patience and a backup of your project

Step-by-Step Migration for App Developers

Step 1: Update Your Flutter SDK

Ensure you have Flutter version 3.44 or higher installed. Run flutter upgrade in your terminal. Verify with flutter --version.

Step 2: Run or Build Your App

The Flutter CLI handles the migration automatically. When you execute flutter run or flutter build ios, it updates your Xcode project to use Swift Package Manager. No manual steps required for the basic switch.

Step 3: Check for Plugin Warnings

During the build, Flutter will print a warning if any of your dependencies haven’t adopted SwiftPM yet. It will then fall back to CocoaPods for those plugins temporarily. Note which plugins are listed – they need to migrate eventually.

Step 4: Handle Unsupported Plugins

If a plugin lacks SwiftPM support and causes a build failure, you have two options:

• File an issue with the plugin maintainer requesting Swift package support.
• Search for an alternative package that already supports SwiftPM.

Remember, CocoaPods support will be removed entirely, so don’t rely on the fallback long-term.

Step 5: Opt Out Temporarily (If Needed)

If SwiftPM causes a breaking issue that blocks your development, you can disable it:

1. Open your project’s pubspec.yaml.
2. Navigate to the flutter section.
3. Add a config block with enable-swift-package-manager: false:

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

After opting out, please file a bug report on the Flutter GitHub repo. Include error details, a list of your plugins and versions, and copies of your Xcode project files. This helps the team fix issues before CocoaPods is fully removed.

Step-by-Step Migration for Plugin Developers

Step 1: Add Swift Package Manager Support

If you haven’t already, create a Package.swift file in your plugin’s root directory. Structure your source files to match the standard Swift package layout. For iOS/macOS, this means moving Objective-C or Swift source into a Sources/ folder.

Step 2: Include FlutterFramework as a Dependency

If you already migrated during the 2025 pilot, there’s one new requirement: add FlutterFramework as a dependency in your Package.swift. Without it, your plugin won’t compile with the latest Flutter. Use:

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

Step 3: Update pub.dev Score

Packages without SwiftPM support now receive a lower score on pub.dev. To maintain good visibility and encourage adoption, complete the migration as soon as possible. As of now, 61% of the top 100 iOS plugins have done so – aim to join them.

Step 4: Test and Publish

Run flutter test and build your plugin for both iOS and macOS to ensure everything works. Then publish a new version to pub.dev. Update your documentation to indicate SwiftPM compatibility.

Tips and Best Practices

• Back up your project before starting – even though Flutter’s migration is smooth, it’s always wise to have a fallback.
• Monitor the Flutter blog for announcements about the final removal of CocoaPods support.
• For app developers: If you encounter errors, check if all your plugins are updated. Use flutter pub outdated to see available upgrades.
• For plugin authors: Consider adding a CI step that validates SwiftPM integration for iOS and macOS builds.
• Join the community – the Flutter team actively seeks feedback. Report issues early to smooth the transition for everyone.
• Remember: CocoaPods will become read-only on December 2, 2026, so plan your migration well before that date to avoid being stuck with unsupported dependencies.

By following these steps, you’ll ensure your Flutter apps and plugins stay up-to-date with the latest dependency management ecosystem, making your development workflow cleaner and more efficient.