# Integrate a Flutter app into your macOS project

> Learn how to integrate a Flutter app into your existing macOS project.



:::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][cocoapods].
:::

[cocoapods]: https://blog.cocoapods.org/CocoaPods-Specs-Repo/
[Swift Package Manager]: https://www.swift.org/documentation/package-manager/

Flutter UI components can be incrementally added
into your existing macOS application using Swift packages.

## Prerequisites

* Flutter 3.44 or later
* Xcode 15.0 or later

### Migrate from legacy integration (if applicable) {: #migrate-legacy-integration}

If you've already integrated Flutter into your macOS app
using embedded frameworks,
you must first remove that integration
before following the Swift Package Manager instructions below.

<details>
  <summary>Expand to see instructions to migrate from embedded frameworks integration</summary>

  If your app was previously integrated using frameworks
  generated by the `flutter build macos-framework` command,
  you must first remove the frameworks from your Xcode project.

  1. Navigate to your target's **General** tab
     and remove all Flutter-related frameworks and libraries
     under **Frameworks, Libraries, and Embedded Content**.

       This includes the `App.xcframework`, `FlutterMacOS.xcframework`,
       `FlutterPluginRegistrant.xcframework`,
       and any Flutter plugins' `xcframework` files.

  1. Remove the Flutter pod from your Podfile
      ```ruby title="MyApp/Podfile" diff
      - pod 'FlutterMacOS', :podspec => '/path/to/MyApp/Flutter/[build mode]/FlutterMacOS.podspec'
      ```

   1. Run `pod install`.
</details>

### Organize your projects relative to each other {: #organize-projects-relatively}

This guide assumes that your existing macOS app
and your Flutter app reside in sibling directories.
If you have a different directory structure,
you will need to adjust the example relative paths accordingly.

:::note

If integrating for the first time,
run the following command to create a new Flutter application:

```console
flutter create my_flutter_app
```

:::

The example directory structure resembles the following:

<FileTree>

- my_flutter_app/
  - macos/
  - lib/
    - main.dart
- MyNativeApp/
  - MyNativeApp.xcodeproj/

</FileTree>

## Integrate with Swift Package Manager {: #integrate-with-swiftpm}

 1. <h3>Build the FlutterNativeIntegration Swift package</h3>

    Within your Flutter application or module, run the following command:

    ```console
    flutter build swift-package --platform macos
    ```

    This generates the following directories:

    <FileTree>

    - my_flutter_app/build/macos/SwiftPackages/
      - FlutterNativeIntegration/ (A Swift package)
      - Scripts/ (Directory of scripts and other files needed)

    </FileTree>

    You can optionally change the location of this output
    with the `--output` flag.

 1. <h3>Add FlutterNativeIntegration to your Xcode project</h3>

    1. In the Project navigator, right click on your project
       and select **Add Files to "MyNativeApp"...**
    1. Navigate to and select the generated
       `FlutterNativeIntegration` Swift package and click **Add**.
    1. Select **Reference files in place** and click **Finish**.
    1. In the File inspector,
       verify the **Location** is **Relative to Project**.
       If it is not, you'll need to move the Flutter output directory
       to be a sibling directory of your native app.

       <DashImage image="development/add-to-app/macos/project-setup-swiftpm/flutternativeintegration-relative-location.png" caption="Relative location of FlutterNativeIntegration shown in Xcode's File inspector." />

    1. Navigate to your target's **General** tab
       and add `FlutterNativeIntegration` under
       **Frameworks, Libraries, and Embedded Content**.

       <DashImage image="development/add-to-app/ios/project-setup-swiftpm/flutternativeintegration-library.png" caption="FlutterNativeIntegration under Frameworks, Libraries, and Embedded Content." />

 1. <h3>Add build settings</h3>

    1. In the **Build Settings** tab,
       set the location of the Flutter app's Swift package output directory:
       ```
       FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
       ```
    1. For custom configurations, set the Flutter build mode.

       Flutter supports three [build modes][]: Debug, Profile, and Release.
       The build mode is determined using the `CONFIGURATION` value.
       If your configuration does not match one of these,
       you can set the `FLUTTER_BUILD_MODE` build setting
       to one of these values.

       <DashImage image="development/add-to-app/ios/project-setup-swiftpm/flutter-build-mode.png" caption="Setting `FLUTTER_BUILD_MODE` for custom configurations under **Build Settings**." />

    1. For **Debug** configurations only, set the following build settings:

       ```
       ENABLE_APP_SANDBOX=YES
       ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
       RUNTIME_EXCEPTION_ALLOW_JIT=YES
       ```

       <DashImage image="development/add-to-app/macos/project-setup-swiftpm/allow-jit-build-setting.png" caption="Set **Allow JIT** (RUNTIME_EXCEPTION_ALLOW_JIT) to **YES** in the target's **Build Settings** for **Debug** configurations only." />

    1. (Optional) Allow Xcode to re-build your Flutter app.

       Add the following build settings to your target
       to allow Xcode to re-build your Flutter app as part of its build.
       This allows you to make changes to your Flutter application
       without needing to re-run `flutter build swift-package`.
       This requires a Flutter installation on the machine.

       ```
       FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
       ENABLE_USER_SCRIPT_SANDBOXING=NO
       ```

       :::tip
       This only re-builds the Flutter app's code.
       If you add new dependencies,
       you’ll need to re-run `flutter build swift-package`.
       :::

 1. <h3>Add Pre-action Run Script to Scheme</h3>

    1. Open **Product** &gt; **Scheme** &gt; **Edit Scheme...**
       &gt; **Build** (in left side bar) &gt; **Pre-action** &gt; **+**
       &gt; **New Run Script Action**

    1. Select your project in the **Provide build settings from** dropdown.

    1. Set the script to the following:
       ```
       /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
       ```

    <DashImage image="development/add-to-app/ios/project-setup-swiftpm/pre-action.png" caption="Pre-action Run Script in scheme editor." />

 1. <h3>Add new run script build phase to your target</h3>

    1. Navigate to your target's **Build Phases**
       &gt; **+** &gt; **New Run Script Phase**

    1. Set the script to the following:
       ```
       /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
       ```
    1. Uncheck **Based on dependency analysis**
    1. Add the following to **Input File Lists**:
       ```
       $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
       ```

    <DashImage image="development/add-to-app/ios/project-setup-swiftpm/build-phase-run-script.png" caption="New Run Script Build Phase under Build Phases." />

{:.steps}

## Next steps

You can now [add a Flutter screen][] to your existing macOS app.

[add a Flutter screen]: /add-to-app/macos/add-flutter-screen
[build modes]: /testing/build-modes