Skip to content

for-app-developers.md

Latest commit

 

History

History
226 lines (151 loc) · 7.63 KB

for-app-developers.md

File metadata and controls

226 lines (151 loc) · 7.63 KB
Raw
title Swift Package Manager for app developers
description How to use Swift Package Manager for native iOS or macOS dependencies

:::note As of the 3.44 release, Flutter uses Swift Package Manager to manage iOS and macOS native dependencies. Flutter continues to support CocoaPods in maintenance mode, however, the CocoaPods registry permanently becomes read-only on December 2, 2026. :::

How to turn on Swift Package Manager

As of the 3.44 release, Flutter's Swift Package Manager (SwiftPM) support is on by default. Upgrading Flutter and running your app automatically adds SwiftPM integration. This makes your project download the Swift packages that your Flutter plugins depend on. To use an older Flutter version, you might need to remove Swift Package Manager integration from the app.

Note that Flutter falls back to CocoaPods for dependencies that don't yet support Swift Package Manager.

[Optional] To check if your project is using SwiftPM:

  1. In Xcode, run the app.

  2. Ensure that Run Prepare Flutter Framework Script runs as a pre-action and that FlutterGeneratedPluginSwiftPackage is a target dependency.

If you previously disabled SwiftPM, you might need to enable it with flutter config --enable-swift-package-manager.

If automatic migration works for you, that's it! You are done with this page.

How to add Swift Package Manager integration manually

When you upgrade to Flutter 3.44 or later and run your app, SwiftPM integration is automatically added. You only need these instructions if problems occurred and you need to manually add SwiftPM integration to your project.

Most developers do not need to do this.

If you experience a problem automatically migrating your project to SwiftPM, please file an issue. Include the error message and, if possible, include a copy of the following files in your issue:

  • ios/Runner.xcodeproj/project.pbxproj
  • ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the xcsheme for the flavor used)

{% render "docs/swift-package-manager/migrate-ios-project-manually.md", site: site %}

{% render "docs/swift-package-manager/migrate-macos-project-manually.md", site: site %}

Add to an existing app (add-to-app)

To use SwiftPM, consult one of the following pages, as appropriate:

Add to a custom Xcode target

Your Flutter Xcode project can have custom Xcode targets to build additional products, like frameworks or unit tests. You can add Swift Package Manager integration to these custom Xcode targets.

Follow the steps in How to add Swift Package Manager integration.

In Step 1 for list item 6, use your custom target instead of the Flutter target.

In Step 2 for list item 6, use your custom target instead of the Flutter target.

How to remove Swift Package Manager integration

When your app is modified to support SwiftPM, the Xcode project is updated to add Flutter plugin dependencies.

To undo this migration:

  1. Turn off Swift Package Manager.

  2. Clean your project:

    flutter clean

  3. Open your app (ios/Runner.xcworkspace or macos/Runner.xcworkspace) in Xcode.

  4. Navigate to Package Dependencies for the project.

  5. Click the FlutterGeneratedPluginSwiftPackage package, then click the button.

  6. Navigate to Frameworks, Libraries, and Embedded Content for the Runner target.

  7. Click FlutterGeneratedPluginSwiftPackage, then click the button.

  8. Go to Product > Scheme > Edit Scheme.

  9. Expand the Build section in the left sidebar.

  10. Click Pre-actions.

  11. Expand Run Prepare Flutter Framework Script.

  12. Click the button.

How to use a Swift Package Manager Flutter plugin that requires a higher OS version

If a Swift Package Flutter Manager plugin requires a higher OS version than the project, you might get an error like this:

Target Integrity (Xcode): The package product 'plugin_name_ios' requires minimum platform version 14.0 for the iOS platform, but this target supports 12.0

To use the plugin:

  1. Open your app (ios/Runner.xcworkspace or macos/Runner.xcworkspace) in Xcode.

  2. Increase your app's target Minimum Deployments.

  3. If you updated your iOS app's Minimum Deployments, regenerate the iOS project's configuration files:

    flutter build ios --config-only

  4. If you updated your macOS app's Minimum Deployments, regenerate the macOS project's configuration files:

    flutter build macos --config-only

How to turn off Swift Package Manager

In general, don't do this. Remember that the CocoaPods registry becomes read-only on December 2, 2026 and disabling SwiftPM won't be allowed in the future.

Disabling Swift Package Manager causes Flutter to use CocoaPods for all dependencies. However, SwiftPM remains integrated with your project. To remove Swift Package Manager integration completely from your project, follow the How to remove Swift Package Manager integration instructions.

Turn off SwiftPM for a single project

In the project's pubspec.yaml file, under the flutter section, set enable-swift-package-manager to false in the config subsection.

# The following section is specific to Flutter packages.
flutter:
  config:
    enable-swift-package-manager: false

This turns off Swift Package Manager for all contributors to this project.

Turn off SwiftPM globally for all projects

Run the following command:

flutter config --no-enable-swift-package-manager

This turns off Swift Package Manager for the current user.

If a project is incompatible with Swift Package Manager, all contributors need to run this command.