Migrating Flutter iOS/macOS Projects from CocoaPods to Swift Package Manager

Introduction

Flutter’s upcoming stable release, version 3.44, marks a significant shift for iOS and macOS development. Starting with this update, Swift Package Manager (SwiftPM) becomes the default dependency manager, replacing CocoaPods. This change eliminates the need to wrestle with Ruby installations or CocoaPods setup just to run your app. CocoaPods is now in maintenance mode and its registry will become read-only on December 2, 2026. While existing builds will continue to work, no new pods or versions will be added after that date. To keep your apps receiving dependency updates and to tap into the Swift package ecosystem, Flutter is transitioning to Apple’s supported solution: Swift Package Manager. This guide walks you through the migration process step by step, covering both app developers and plugin maintainers.

What You Need

• Flutter SDK version 3.44 or later (stable channel)
• Xcode (latest version recommended)
• An existing Flutter project with iOS and/or macOS support
• pubspec.yaml file for your project
• Basic familiarity with the Flutter CLI and terminal

Step-by-Step Migration Guide

Step 1: Update Flutter to Version 3.44+

Before you begin, ensure you’re running Flutter 3.44 or later. Run the following command in your terminal:

flutter upgrade

This will bring in the latest stable release that includes SwiftPM as the default. Verify the version with:

flutter --version

Look for version number 3.44.0 or higher.

Step 2: Run Your iOS/macOS App Normally

Once Flutter is updated, simply build or run your app as usual. The Flutter CLI now automatically handles the migration for app developers. When you execute flutter run or flutter build ios (or macOS equivalents), the CLI will update your Xcode project to use Swift Package Manager instead of CocoaPods. No manual steps are required for most projects.

If your app has plugins that haven’t yet adopted SwiftPM, Flutter will print a warning during the build, listing exactly which dependencies are unsupported. In that case, the CLI temporarily falls back to CocoaPods for those specific plugins, ensuring your build still succeeds—but this is only a temporary measure.

Step 3: Handle Plugin Warnings (If Any)

If you see warnings about plugins that lack Swift Package Manager support, take note. CocoaPods support will be removed entirely in the future, so those plugins need to be updated. Your options:

• File an issue with the plugin’s maintainer requesting SwiftPM support.
• Find an alternative package that already supports SwiftPM.
• Wait for the plugin to be updated (but be aware of the December 2026 deadline).

Plugin developers are encouraged to migrate quickly—note that packages without SwiftPM support now receive lower pub.dev scores to incentivize adoption.

Step 4: Opt Out Temporarily (If You Encounter Breaking Issues)

If SwiftPM causes a critical problem in your project, you can temporarily disable it. This is a safety net, not a permanent solution. To opt out:

1. Open your project’s pubspec.yaml file.
2. Locate the flutter section.
3. Add or edit the config block to set enable-swift-package-manager to false:

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

After making this change, rebuild your app. CocoaPods will be used again for that project. However, remember that CocoaPods will eventually stop receiving updates. If you need to opt out, please file a bug report using the Flutter GitHub issue template. Include error details, a list of your plugins and versions, and copies of your Xcode project files to help the team resolve the issue before CocoaPods is fully 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. Currently, about 61% of the top 100 iOS plugins have migrated. To encourage full adoption, pub.dev scores are reduced for packages without SwiftPM support. Here’s what to do:

• Create a Package.swift file in your plugin’s root directory.
• Move your source files to match the standard Swift package structure (e.g., Sources/YourPluginName/).
• Define dependencies as needed in the Package.swift manifest.

Step 6: Existing Migrated Plugins – Add FlutterFramework Dependency

If you already migrated your plugin during the 2025 pilot phase, one additional step is required: you must add FlutterFramework as a dependency in your Package.swift file. This ensures compatibility with the new Flutter release. For detailed instructions, refer to the Flutter migration docs for plugin developers.

Tips for a Smooth Transition

• Test your app thoroughly after migration. Run both debug and release builds on iOS and macOS to catch any SwiftPM-related issues early.
• Keep an eye on plugin updates. If a plugin you rely on hasn’t migrated, check its repository periodically for new releases that include SwiftPM support.
• Use the warning messages as a checklist. The Flutter CLI lists unsupported plugins—address them one by one to ensure a full transition before CocoaPods is deprecated.
• Do not rely on the opt-out flag permanently. Use it only as a temporary workaround while you update your plugins or wait for maintainer fixes.
• Contribute to the community. If you’re a plugin developer, migrating your package helps the entire Flutter ecosystem. If you’re an app developer, report any issues you encounter to help improve the tooling.
• Back up your project before making any structural changes, especially if you’re manually editing Package.swift files.