Mastering the Shift: How to Migrate Your Flutter Project from CocoaPods to Swift Package Manager

Introduction

Flutter's upcoming stable release (version 3.44) marks a major milestone: Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps, replacing the long-standing CocoaPods. This change eliminates the need to manage Ruby and CocoaPods installations and opens the door to Apple's native package ecosystem. CocoaPods will enter maintenance mode and its registry becomes read-only on December 2, 2026; while existing builds remain functional, no new updates will be published after that date. To keep your Flutter apps up‑to‑date and future‑proof, migration to SwiftPM is essential. This guide walks you through every step—whether you're an app developer or a plugin maintainer—so the transition is smooth and your projects stay healthy.

What You Need

• Flutter SDK – the latest stable version (3.44 or later). Update via flutter upgrade.
• Xcode – version 14 or higher (SwiftPM integration is tight).
• macOS – to build iOS and macOS apps.
• Basic knowledge of Flutter project structure and pubspec.yaml.
• Plugin developers: a Package.swift understanding helps; for already‑migrated plugins, you must add the Flutter framework dependency.

Step-by-Step Migration for App Developers

Step 1: Understand the Transition Timeline

Before touching any configuration, know the key dates: CocoaPods goes read‑only on December 2, 2026, and Flutter will eventually remove fallback support. Starting with Flutter 3.44, SwiftPM is the default – but the CLI still temporarily uses CocoaPods for plugins that haven’t migrated yet. Your goal is to get all your dependencies onto SwiftPM before the cut‑off.

Step 2: Run Your App Normally – Let the CLI Do the Heavy Lifting

The easiest path: simply execute flutter run or flutter build ios for your project. The Flutter CLI automatically updates your Xcode project to use Swift Package Manager. Behind the scenes, it scans your dependencies and adapts the workspace. Important: always commit your project files before running to review changes safely.

Step 3: Check for Warnings About Unsupported Plugins

During the build process, Flutter prints a clear warning listing every plugin that still relies on CocoaPods. For those plugins, the CLI temporarily falls back to CocoaPods so your app still compiles. However, this fallback will not be available forever. If you see such warnings, you have two options:

• Option A: Wait for the plugin maintainer to adopt SwiftPM – they receive a lower pub.dev score until they do, which encourages updates.
• Option B: Find an alternative plugin that already supports SwiftPM. File an issue with the unmaintained plugin’s repo to request migration.

Step 4: (Optional) Disable SwiftPM If You Hit a Breaking Issue

If SwiftPM introduces a bug that blocks your build, you can temporarily revert to CocoaPods. Open your pubspec.yaml, locate the flutter section, and add this configuration block:

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

This opt‑out is a safety net – but please report the issue 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 the problem before CocoaPods removal.

Step-by-Step Migration for Plugin Developers

Step 5: Add SwiftPM Support to Your Plugin (if you haven't already)

To ensure your plugin remains usable and maintains a high pub.dev score, you must add Swift Package Manager support. Currently, about 61% of the top 100 iOS plugins have migrated. Here’s how:

1. Create a Package.swift file at the root of your plugin’s iOS/macOS folder.
2. Define your package name, platforms (iOS 12.0+, macOS 10.14+), and dependencies.
3. Move your source files to follow the standard Swift package structure (e.g., Sources/PluginName/).
4. Ensure your Package.swift exports the necessary public interfaces.

For detailed syntax, refer to the Flutter migration docs for plugin developers.

Step 6: If You Migrated During the 2025 Pilot – Add FlutterFramework Dependency

Plugins that already migrated in the early 2025 pilot now require one additional step: you must explicitly add FlutterFramework as a dependency in your Package.swift. This ensures proper linking with the Flutter engine. Add the following clause:

.target(
    name: "YourPlugin",
    dependencies: [
        .product(name: "FlutterFramework", package: "Flutter")
    ]
)

Make sure you also include the Flutter package repository or use a local path as appropriate. Without this dependency, your plugin may fail to build under the new manager.

Tips for a Smooth Migration

• Start early: Don’t wait until December 2026. The earlier you migrate, the earlier you benefit from SwiftPM’s speed and tighter Xcode integration.
• Monitor your pub.dev score: If you’re a plugin maintainer, your package score drops without SwiftPM support. Keep an eye on it.
• Test on multiple Xcode versions: SwiftPM works best with Xcode 14+, but test on the version your CI uses.
• Use the Flutter CLI’s verbose mode: Run flutter run --verbose to see exactly which dependencies are resolved via CocoaPods fallback.
• File issues promptly: If a breaking change occurs, report it with logs. The Flutter team is actively improving the migration tooling.
• Keep backups: Before running flutter pub upgrade or flutter build, commit your ios/ and macos/ folders to version control.
• Join the community: Check the Flutter GitHub discussions for common issues and solutions.

By following these steps, you'll ensure your Flutter app or plugin is ready for the Swift Package Manager era—no more Ruby, no more CocoaPods headaches. Happy coding!