Migrating Your Flutter App from CocoaPods to Swift Package Manager: A Practical Guide

Introduction

The Flutter ecosystem is evolving: Swift Package Manager (SwiftPM) will become the default dependency manager for iOS and macOS apps starting with Flutter 3.44. This change simplifies your workflow by eliminating the need to manage Ruby installations or CocoaPods dependencies. CocoaPods is entering maintenance mode, and its registry will become read‑only on December 2, 2026. To stay current and gain access to the modern Swift package ecosystem, migrating to SwiftPM is essential. This guide provides clear, step‑by‑step instructions for both app developers and plugin authors to make the transition smooth and error‑free.

Migrating Your Flutter App from CocoaPods to Swift Package Manager: A Practical Guide

What You Need

A Flutter project (version 3.44 or later recommended)
Xcode (latest stable version) installed on macOS
Basic familiarity with the terminal and Flutter CLI commands
For plugin developers: access to your plugin’s source repository and understanding of Swift package structure
An internet connection to download dependencies

Step‑by‑Step Guide

Step 1: Update Your Flutter SDK

Ensure you are running Flutter 3.44 or a later stable release. If you are on an older version, update using flutter upgrade. The new migration logic is built into the CLI, so this step is critical. Verify your version with flutter --version.

Step 2: Build or Run Your App

For app developers, the migration is largely automatic. Simply run your app with flutter run (targeting iOS or macOS) or build with flutter build ios/flutter build macos. The Flutter CLI will detect the project and update your Xcode project to use Swift Package Manager. No manual intervention is required for most cases.

Step 3: Handle Plugin Warnings

After running, check the console output. If any of your plugins have not yet adopted SwiftPM, Flutter prints a warning listing those unsupported dependencies. In such cases, Flutter temporarily falls back to CocoaPods for those plugins, so your app should still compile. However, because CocoaPods support will eventually be removed, you must take action: contact the plugin maintainer (file an issue on their repository) or search for an alternative package that already supports SwiftPM.

Step 4: Temporary Rollback (If Needed)

If you encounter a breaking issue caused by the SwiftPM migration, you can temporarily disable it. Open your pubspec.yaml file and add the following under the flutter section:

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

This forces Flutter to keep using CocoaPods for the current project. If you 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. This helps the team resolve issues before CocoaPods is fully deprecated.

Step 5: Plugin Developers – Add Swift Package Support

If you maintain an iOS or macOS Flutter plugin, you must add SwiftPM support to avoid a drop in your pub.dev score (currently 61% of top 100 plugins have migrated). To do so:

Create a Package.swift file in your plugin’s root directory.
Move your existing source files to follow the standard Swift package layout (e.g., Sources/YourPluginName/).
Ensure your package manifest declares the appropriate platforms and dependencies.
If you already migrated during the 2025 pilot, you must add FlutterFramework as a dependency in your Package.swift file. This is a new requirement.

Refer to the official Flutter migration docs for plugin developers for detailed instructions.

Step 6: Test and Upload

After adding SwiftPM support, test your plugin thoroughly with a sample Flutter app. Ensure both iOS and macOS builds succeed and that all functionality remains intact. Then publish the updated version to pub.dev to help the Flutter community transition smoothly.

Tips for a Smooth Transition

Back up your project before testing the migration, especially if you disable SwiftPM and need to revert.
Monitor the console for warnings about unsupported plugins – these are your cue to act early.
Check plugin pub.dev pages for migration status. Look for tags like “SwiftPM” in the README.
Use the Flutter GitHub issue tracker to report problems with the migration tooling; include detailed logs.
For plugin authors: prioritize migrating your most depended‑upon plugins to SwiftPM, as they have the largest impact.
Keep Xcode updated to the latest stable version – SwiftPM support improves with each release.
Read the official Flutter migration docs (for app developers and for plugin developers) for the most authoritative guidance.

Tags: