Migrating Your Flutter Projects to Swift Package Manager: A Step-by-Step Guide

Flutter's upcoming stable release (version 3.44) introduces a major change: Swift Package Manager (SwiftPM) becomes the default dependency manager for iOS and macOS apps, replacing CocoaPods. This shift eliminates the need for Ruby installations and manual CocoaPods setup, streamlining your workflow. CocoaPods is now in maintenance mode, and its registry will become read-only on December 2, 2026. While existing builds continue to work, no new updates will be available. To keep your projects running smoothly with the latest dependencies and to unlock the full Swift package ecosystem, follow this guide to migrate your Flutter projects—whether you're an app developer or a plugin creator.

What You Need

• Flutter SDK 3.44 or later (the stable channel release that enables SwiftPM by default)
• Xcode 15 or newer (required for Swift Package Manager support)
• An existing Flutter project targeting iOS and/or macOS
• Basic knowledge of pubspec.yaml and Xcode project files

Step-by-Step Guide for App Developers

Step 1: Update Flutter and Verify Your Setup

Ensure you have Flutter 3.44 or later installed. Run flutter upgrade in your terminal to get the latest stable version. After updating, confirm with flutter --version. Also make sure Xcode is up to date (version 15+).

Step 2: Run or Build Your App – Automatic Migration

Flutter's CLI automatically converts your Xcode project to use Swift Package Manager when you execute flutter build ios, flutter build macos, or launch the app with flutter run. There's no manual configuration needed—the migration happens behind the scenes. After the first build, check your Xcode project settings; you should see Swift Package references instead of CocoaPods.

Step 3: Check for Unsupported Plugins

If any of your dependencies still rely on CocoaPods, Flutter will print a warning during the build process. It will list exactly which plugins haven't adopted SwiftPM yet. Flutter temporarily falls back to CocoaPods for those plugins, but this is a stopgap—support will be removed entirely after December 2026.

Step 4: Handle Unsupported Plugins

When you see a warning for a plugin:

• Check for updates: Look for a newer version of the plugin on pub.dev that includes Swift Package Manager support.
• File an issue: If no update exists, contact the plugin maintainer using the plugin's issue tracker and request SwiftPM support.
• Find an alternative: Search for similar packages that already support Swift Package Manager.

If a broken plugin prevents your build from succeeding, follow the steps in Step 5 to temporarily opt out.

Step 5: Opt Out of SwiftPM (If Necessary)

If SwiftPM causes a critical issue, you can revert to CocoaPods for your project. Open your pubspec.yaml file and add the following under the flutter section:

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

This disables the automatic migration and forces Flutter to use CocoaPods for both iOS and macOS targets. After making this change, clean your build (flutter clean) and rebuild.

Step 6: Report Issues to Flutter Team

If you had to opt out, please file a bug report using the Flutter GitHub issue template. Include:

• Error details and logs
• List of your plugins and their versions (from pubspec.lock)
• Copies of your Xcode project files (like Runner.xcodeproj)

This helps the Flutter team resolve compatibility issues before CocoaPods is fully removed.

Step-by-Step Guide for Plugin Developers

Step 1: Add Swift Package Manager Support

If your plugin doesn't support SwiftPM yet, you need to create a Package.swift file in the root of your plugin's iOS/macOS source directory. Move your existing source files into a Sources/PluginName folder to match the standard Swift package layout. Define your package targets, dependencies, and products in the Package.swift file.

Step 2: For Plugins Already Migrated in the 2025 Pilot – Add FlutterFramework Dependency

If you participated in the earlier pilot program and already have a Package.swift, you must add FlutterFramework as an explicit dependency. Insert the following in your Package.swift:

dependencies: [
    .package(url: "https://github.com/flutter/flutter", from: "3.44.0")
],
targets: [
    .target(
        name: "YourPluginName",
        dependencies: ["FlutterFramework"]
    )
]

Replace the version number with the Flutter release you're targeting. This step is mandatory for the new default to work correctly.

Step 3: Publish an Updated Version

After updating your plugin, publish a new version to pub.dev. Make sure the pubspec.yaml metadata reflects the changes, and update the CHANGELOG. Your plugin's pub.dev score will improve once it supports SwiftPM, since unsupported packages now receive lower scores.

Step 4: Test with a Fresh Flutter Project

Create a new Flutter project that uses your plugin and run a build for iOS. Verify that no CocoaPods warnings appear and that all dependencies resolve via SwiftPM. This ensures maximum compatibility for your users.

Tips for a Smooth Migration

1. Migrate Early: Start the migration before the December 2026 deadline. App developers should update their projects now to identify problematic plugins early.
2. Keep an Eye on Warnings: Always read the build output. Flutter will clearly list unsupported plugins, making it easy to track what needs attention.
3. Communicate with Maintainers: If you depend on a plugin, politely request SwiftPM support. Plugin developers are incentivized by pub.dev scores to migrate.
4. Test Thoroughly: After migration, run all your app’s features across iOS and macOS. SwiftPM might handle dependencies differently, so verify behavior like asset loading, native code integration, and plugin initialization.
5. Use the Opt-Out Sparingly: Only disable SwiftPM if you have a genuine blocking issue. Overusing it will leave you on a deprecated toolchain that will eventually break.
6. Backup Your Project: Before making any changes, commit your code to version control. This makes it easy to revert the opt-out config if needed.

By following these steps, you'll ensure your Flutter apps stay up-to-date with the latest dependency management practices and avoid being left behind when CocoaPods support ends.