How to Seamlessly Shift from CocoaPods to Swift Package Manager in Flutter

Introduction

Flutter's upcoming stable release (version 3.44) makes Swift Package Manager (SwiftPM) the default dependency manager for iOS and macOS apps. This change bids farewell to CocoaPods, which is now in maintenance mode and will become read-only on December 2, 2026. For app developers, the transition is mostly automatic, but plugin authors must take proactive steps to ensure their packages remain compatible. This guide walks you through everything you need to know—from updating your environment to troubleshooting potential hiccups—so you can move forward without missing a beat.

What You Need

• Flutter SDK version 3.44 or later (check with flutter --version)
• Xcode (latest stable version recommended)
• An existing Flutter project that targets iOS or macOS
• Ruby (optional, for fallback if you temporarily need CocoaPods)
• A GitHub account for filing issues if you encounter problems
• Basic familiarity with the command line and pubspec.yaml editing

Step 1: Update Your Flutter SDK to 3.44 or Later

If you haven't already, upgrade to the latest stable Flutter release. Run:

flutter upgrade

Verify the installation with flutter --version. This step ensures the CLI includes the automatic migration logic for Swift Package Manager. Note that the change takes effect only for projects built with version 3.44+.

Step 2: Refresh Your Project Dependencies

Navigate to your project directory and run:

flutter pub get

This command reads pubspec.yaml and fetches the latest versions of your dependencies. Pay attention to any warnings printed in the console. Flutter will list plugins that haven't yet adopted Swift Package Manager. Those plugins will continue to work via a temporary fallback to CocoaPods, but they won't receive updates after the CocoaPods registry closes.

Step 3: Build or Run Your App for iOS or macOS

Trigger a build or run using the Flutter CLI:

flutter run -d ios

or for macOS:

flutter run -d macos

During this process, the CLI automatically converts your Xcode project to use Swift Package Manager (SwiftPM) for all dependencies that support it. You'll see output indicating that CocoaPods is being replaced with Swift package references. If all goes well, your app will compile and run without any additional configuration.

Step 4: Verify the Integration in Xcode

Open your project's .xcworkspace file in Xcode. Navigate to File > Project Settings and then to the Package Dependencies tab. You should see a list of packages managed by Swift Package Manager. Also check that the Podfile is no longer present or is empty. If you see both CocoaPods and SwiftPM entries, it may indicate a partial migration—review the warnings from Step 2.

Step 5: For Plugin Authors – Adopt Swift Package Manager

If you maintain a Flutter plugin with iOS or macOS code, you must add Swift Package Manager support before December 2026. Here's how:

1. Add a Package.swift file at the root of your iOS/macOS plugin folder. This file defines the package's name, products, targets, and dependencies.
2. Move your source files to comply with Swift package conventions (e.g., Sources/PluginName/). If you already migrated during the 2025 pilot, you must add FlutterFramework as a dependency in Package.swift—this is a new requirement for the final transition.
3. Test your plugin with a sample Flutter app using SwiftPM. Run flutter build ios --no-cocoa-pods to force SwiftPM usage.
4. Submit your updated plugin to pub.dev. Packages without SwiftPM support will receive lower pub.dev scores, so migration is strongly encouraged.

Step 6: Opt Out Temporarily If Needed

If SwiftPM causes a breaking issue in your project, you can temporarily disable it. Open your pubspec.yaml and under the flutter section, add:

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

This reverts to using CocoaPods for all dependencies. Important: This is a temporary workaround. If you use it, please file a bug report using the Flutter GitHub issue template. Include error logs, a list of your plugins and versions, and your Xcode project files. This feedback helps the Flutter team resolve issues before CocoaPods support is fully removed.

Tips for a Smooth Migration

• Backup your project before making changes—especially if you need to opt out temporarily. Use version control (git) to track modifications.
• Check plugin compatibility early. Visit pub.dev and look for a SwiftPM badge or mention in the README. If a critical plugin hasn't migrated, reach out to its maintainer or consider alternatives.
• Monitor Flutter releases and changelogs. The team will announce deprecation warnings and final removal dates.
• For plugin authors, prioritize migration before December 2026. The automatic fallback in Flutter will eventually disappear, leaving your package non-functional for iOS/macOS builds.
• Stay engaged with the community—file issues, share your experiences, and help improve the migration tooling.

Moving from CocoaPods to Swift Package Manager is a forward-looking change that aligns Flutter with Apple's modern dependency ecosystem. While it requires some attention from plugin maintainers, app developers will find the transition nearly effortless. By following these steps and keeping the tips in mind, you'll ensure your Flutter projects remain healthy and up-to-date.