Contents

Swift Package Manager for app developers

Contents

Flutter's Swift Package Manager integration has several benefits:

  1. Provides access to the Swift package ecosystem. Flutter plugins can use the growing ecosystem of Swift packages.
  2. Simplifies Flutter installation. Xcode includes Swift Package Manager. You don't need to install Ruby and CocoaPods if your project uses Swift Package Manager.

If you find a bug in Flutter's Swift Package Manager support, open an issue.

How to turn on Swift Package Manager

#

Flutter's Swift Package Manager support is turned off by default. To turn it on:

  1. Switch to Flutter's main channel:

    sh
    flutter channel main --no-cache-artifacts

  2. Upgrade to the latest Flutter SDK and download artifacts:

    sh
    flutter upgrade

  3. Turn on the Swift Package Manager feature:

    sh
    flutter config --enable-swift-package-manager

Using the Flutter CLI to run an app migrates the project to add Swift Package Manager integration. This makes your project download the Swift packages that your Flutter plugins depend on. An app with Swift Package Manager integration requires Flutter version 3.24 or higher. To use an older Flutter version, you will need to remove Swift Package Manager integration from the app.

Flutter falls back to CocoaPods for dependencies that do not support Swift Package Manager yet.

How to turn off Swift Package Manager

#

Disabling Swift Package Manager causes Flutter to use CocoaPods for all dependencies. However, Swift Package Manager 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 for a single project

#

In the project's pubspec.yaml file, under the flutter section, add disable-swift-package-manager: true.

pubspec.yaml
yaml
# The following section is specific to Flutter packages.
flutter:
  disable-swift-package-manager: true

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

Turn off globally for all projects

#

Run the following command:

sh
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.

How to add Swift Package Manager integration

#

Add to a Flutter app

#

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project the next time you run your app using the CLI. This migration updates your Xcode project to use Swift Package Manager to add Flutter plugin dependencies.

To migrate your project:

  1. Turn on Swift Package Manager.

  2. Run the iOS app using the Flutter CLI.

    If your iOS project doesn't have Swift Package Manager integration yet, the Flutter CLI tries to migrate your project and outputs something like:

    flutter run
Adding Swift Package Manager integration...

    The automatic iOS migration modifies the ios/Runner.xcodeproj/project.pbxproj and ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme files.

  3. If the Flutter CLI's automatic migration fails, follow the steps in add Swift Package Manager integration manually.

[Optional] To check if your project is migrated:

  1. Run the app in Xcode.

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

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    Ensure Run Prepare Flutter Framework Script runs as a pre-action

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project the next time you run your app using the CLI. This migration updates your Xcode project to use Swift Package Manager to add Flutter plugin dependencies.

To migrate your project:

  1. Turn on Swift Package Manager.

  2. Run the macOS app using the Flutter CLI.

    If your macOS project doesn't have Swift Package Manager integration yet, the Flutter CLI tries to migrate your project and outputs something like:

    flutter run -d macos
Adding Swift Package Manager integration...

    The automatic iOS migration modifies the macos/Runner.xcodeproj/project.pbxproj and macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme files.

  3. If the Flutter CLI's automatic migration fails, follow the steps in add Swift Package Manager integration manually.

[Optional] To check if your project is migrated:

  1. Run the app in Xcode.

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

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    Ensure Run Prepare Flutter Framework Script runs as a pre-action

Add to a Flutter app manually

#

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project to use Swift Package Manager the next time you run your app using the CLI.

However, the Flutter CLI tool might be unable to migrate your project automatically if there are unexpected modifications.

If the automatic migration fails, use the steps below to add Swift Package Manager integration to a project manually.

Before migrating manually, file an issue; this helps the Flutter team improve the automatic migration process. 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)

Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

#

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

  2. Navigate to Package Dependencies for the project.

    The project's package dependencies
    The project's package dependencies

  3. Click add.

  4. In the dialog that opens, click Add Local....

  5. Navigate to ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage and click Add Package.

  6. Ensure that it's added to the Runner target and click Add Package.

    Ensure that the package is added to the target
    Ensure that the package is added to the Runner target

  7. Ensure that FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content.

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    Ensure that FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content

Step 2: Add Run Prepare Flutter Framework Script Pre-Action

#

The following steps must be completed for each flavor.

  1. Go to Product > Scheme > Edit Scheme.

  2. Expand the Build section in the left side bar.

  3. Click Pre-actions.

  4. Click add and select New Run Script Action from the menu.

  5. Click the Run Script title and change it to:

    Run Prepare Flutter Framework Script

  6. Change the Provide build settings from to the Runner app.

  7. Input the following in the text box:

    sh
    "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare

    Add Run Prepare Flutter Framework Script build pre-action
    Add Run Prepare Flutter Framework Script build pre-action

Step 3: Run app

#

  1. Run the app in Xcode.

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

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    Ensure Run Prepare Flutter Framework Script runs as a pre-action

  3. Ensure that the app runs on the command line with flutter run.

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project to use Swift Package Manager the next time you run your app using the CLI.

However, the Flutter CLI tool might be unable to migrate your project automatically if there are unexpected modifications.

If the automatic migration fails, use the steps below to add Swift Package Manager integration to a project manually.

Before migrating manually, file an issue; this helps the Flutter team improve the automatic migration process. Include the error message and, if possible, include a copy of the following files in your issue:

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

Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

#

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

  2. Navigate to Package Dependencies for the project.

    The project's package dependencies
    The project's package dependencies

  3. Click add.

  4. In the dialog that opens, click the Add Local....

  5. Navigate to macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage and click the Add Package.

  6. Ensure that it's added to the Runner Target and click Add Package.

    Ensure that the package is added to the target
    Ensure that the package is added to the Runner target

  7. Ensure that FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content.

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    Ensure that FlutterGeneratedPluginSwiftPackage was added to Frameworks, Libraries, and Embedded Content

Step 2: Add Run Prepare Flutter Framework Script Pre-Action

#

The following steps must be completed for each flavor.

  1. Go to Product > Scheme > Edit Scheme.

  2. Expand the Build section in the left side bar.

  3. Click Pre-actions.

  4. Click the add button and select New Run Script Action from the menu.

  5. Click the Run Script title and change it to:

    Run Prepare Flutter Framework Script

  6. Change the Provide build settings from to the Runner target.

  7. Input the following in the text box:

    sh
    "$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare

    Add Run Prepare Flutter Framework Script build pre-action
    Add Run Prepare Flutter Framework Script build pre-action

Step 3: Run app

#

  1. Run the app in Xcode.

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

    Ensure runs as a pre-action
    Ensure Run Prepare Flutter Framework Script runs as a pre-action

  3. Ensure that the app runs on the command line with flutter run.

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

#

Flutter's Swift Package Manager support doesn't work with add-to-app scenarios.

To keep current on status updates, consult flutter#146957.

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 to a project manually.

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

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

How to remove Swift Package Manager integration

#

To add Swift Package Manager integration, the Flutter CLI migrates your project. This migration updates your Xcode project to add Flutter plugin dependencies.

To undo this migration:

  1. Turn off Swift Package Manager.

  2. Clean your project:

    sh
    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 remove.

    The to remove
    The FlutterGeneratedPluginSwiftPackage to remove

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

  7. Click FlutterGeneratedPluginSwiftPackage, then click the remove.

    The to remove
    The FlutterGeneratedPluginSwiftPackage to remove

  8. Go to Product > Scheme > Edit Scheme.

  9. Expand the Build section in the left side bar.

  10. Click Pre-actions.

  11. Expand Run Prepare Flutter Framework Script.

  12. Click delete.

    The build pre-action to remove
    The build pre-action to remove

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, increase the Minimum Deployments of your app's target.

The target's Minimum Deployments setting
The target's Minimum Deployments setting

Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-07-31. View source or report an issue.