Migrating from CocoaPods to Swift Package Manager in Flutter: A Step-by-Step Guide

By ✦ min read

Introduction

Flutter is making a major shift in how iOS and macOS dependencies are managed. Starting with Flutter 3.44, Swift Package Manager (SwiftPM) becomes the default dependency manager, replacing the long‑standing CocoaPods. CocoaPods has entered maintenance mode, and its registry will become read‑only on December 2, 2026. While existing builds continue to work, no new versions or pods will be added after that date. This transition ensures your apps receive ongoing dependency updates and gives you access to Apple’s modern package ecosystem.

Migrating from CocoaPods to Swift Package Manager in Flutter: A Step-by-Step Guide

This guide walks you through the migration, whether you’re an app developer or a plugin maintainer. You’ll find clear steps, prerequisites, and tips to make the move smooth and trouble‑free.

What You Need

Flutter SDK 3.44 or later (the stable release that introduces SwiftPM as default)
Xcode (latest version recommended)
A Flutter project targeting iOS or macOS
If you’re a plugin developer: a plugin with existing iOS/macOS source code
Basic familiarity with pubspec.yaml and command‑line tools

Step‑by‑Step Migration

For App Developers

Update Flutter to version 3.44 or higher.
Run flutter upgrade to get the latest stable release. Verify the version with flutter --version — you should see 3.44.0 or above.
Build or run your iOS/macOS app as usual.
The Flutter CLI automatically handles the migration. When you execute flutter run, flutter build ios, or flutter build macos, the CLI updates your Xcode project to use Swift Package Manager instead of CocoaPods.
Check for warnings about unsupported plugins.
After the build, look at the console output. If any of your dependencies haven’t adopted SwiftPM yet, Flutter will print a warning listing those plugins. The framework then temporarily falls back to CocoaPods for those dependencies so your app continues to build.
Manage unsupported plugins.
If a plugin remains on CocoaPods and causes a build failure, you have two options:
- File an issue with the plugin’s maintainer to request Swift Package Manager support, or
- Find an alternative package that already supports SwiftPM.
Remember, CocoaPods support will be removed entirely in the future, so it’s best to migrate or replace dependencies now.
Opt out temporarily (if needed).
If the automatic migration causes a breaking issue, you can disable SwiftPM for your project. Open your pubspec.yaml file and add the following under the flutter section:
```
flutter:
  config:
    enable-swift-package-manager: false
```
After making this change, run flutter clean and rebuild. If you opt out, please file a bug report using the Flutter GitHub issue template with error details, your plugin list and versions, and copies of your Xcode project files. Your report helps the team fix issues before CocoaPods support is completely removed.

For Plugin Developers

If you maintain a Flutter plugin with iOS or macOS support, you must add Swift Package Manager support if you haven’t already. Currently, 61% of the top 100 iOS plugins have migrated. The remaining 39% are critical for a complete transition. To encourage adoption, packages without SwiftPM support now receive lower pub.dev scores until they migrate.

Add a Package.swift file to your plugin.
Create a Package.swift file at the root of your plugin’s iOS/macOS directory. This file declares the module name, dependencies, and source files. Follow Apple’s standard Swift package structure.
Move your source files to match the Swift package layout.
Reorganize your iOS/macOS source code into the Sources/YourPluginName/ directory, as required by Swift packages. Ensure all Objective‑C or Swift files are correctly placed.
If you migrated during the 2025 pilot, add FlutterFramework as a dependency.
If you already added SwiftPM support during the Flutter 2025 pilot, you must complete one extra step: include FlutterFramework as a dependency in your Package.swift file. Add it under the dependencies array with the appropriate version rule (usually "1.0.0" ..< "2.0.0" or a specific version). This ensures your plugin links correctly with the Flutter engine.

Example snippet:
```
dependencies: [
    .package(url: "https://github.com/flutter/flutter.git", from: "3.0.0")
]
```
For full details, refer to the Flutter migration docs for plugin developers.

Tips & Best Practices

File issues early. If you hit a SwiftPM‑related bug, report it via the Flutter GitHub issue template. Include error logs, plugin list, and Xcode project files to speed up the fix.
Keep your plugins updated. Regularly run flutter pub outdated to see which plugins still lack SwiftPM support. Encourage maintainers by commenting on their repositories.
Test your builds after migration. Run your app on both simulators and real devices to ensure everything links correctly. Pay special attention to plugins that relied on CocoaPods‑specific features (like use_frameworks! or subspecs).
Monitor pub.dev scores. If you’re a plugin developer, check your package’s score after migration. Adding SwiftPM support will restore points and improve discoverability.
Plan for the December 2026 deadline. CocoaPods will become read‑only on that date. Make sure all your projects and plugins are fully migrated before then to avoid dependency resolution issues.

By following these steps, you’ll ensure a seamless transition to Swift Package Manager in Flutter — leaving behind the complexity of Ruby and CocoaPods setups. Welcome to a cleaner, Apple‑supported dependency ecosystem!

Tags: