Integrate a Flutter app into your iOS project

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

• Flutter 3.44 or later
• Xcode 15.0 or later

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

The legacy integration guide is preserved for reference, but will not receive ongoing maintenance.

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

The example directory structure resembles the following:

1. Build the FlutterNativeIntegration Swift package

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

   flutter build swift-package --platform ios
   

   content_copy

   This will generate the following directories:

   • my_flutter_app/build/ios/SwiftPackages/

     • FlutterNativeIntegration/(A Swift package)
     • Scripts/(Directory of scripts and other files needed)

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

2. Add FlutterNativeIntegration to your Xcode project

   1. Open your existing iOS app in Xcode.

   2. In the Project navigator, right click on your project and select Add Files to "MyNativeApp"...

   3. Navigate to and select the generated FlutterNativeIntegration Swift package and click Add.

   4. Select Reference files in place and click Finish.

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

      

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

3. Add build settings

   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/ios/SwiftPackages
      

      content_copy

   2. 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. If your configuration does not match one of these, you can set the FLUTTER_BUILD_MODE build setting to one of these values.

      

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

      Add the below 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 Flutter to be installed on the machine.

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

      content_copy

4. Add Pre-action Run Script to Scheme

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

   2. Select your project in the Provide build settings from dropdown.

   3. Set the script to the following:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
      

      content_copy
   

5. Add New Run Script Build Phase to Target

   1. Navigate to your target's Build Phases > + > New Run Script Phase

   2. Set the script to the following:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
      

      content_copy

   3. Uncheck Based on dependency analysis

   4. Add the following to Input File Lists:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
      

      content_copy
   

6. (Optional) Set LLDB Init File

   Using Flutter's LLDB Init File improves performance when debugging on physical iOS 26+ devices.

   1. Open Product > Scheme > Edit Scheme... > Run (in left side bar).

   2. Set the LLDB Init File to the following path:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/flutter_lldbinit
      

      content_copy

      Alternatively, if your scheme already has an LLDB Init File, you can add Flutter's LLDB file to it. The path to Flutter's LLDB Init File must be relative to the location of your project's LLDB Init File.

      command source --relative-to-command-file "../my_flutter_app/build/ios/SwiftPackages/Scripts/flutter_lldbinit"
      

      content_copy

On iOS 14 and later, enable the Dart multicast DNS service in the Debug version of your iOS app. This adds debugging functionalities such as hot-reload and DevTools using flutter attach.

To set local network privacy permissions only in the Debug version of your app, create a separate Info.plist per build configuration. SwiftUI projects start without an Info.plist file. If you need to create a property list, you can do so through Xcode or text editor. The following instructions assume the default Debug and Release. Adjust the names as needed depending on your app's build configurations.

1. Create a new property list.

   1. Open your project in Xcode.

   2. In the Project Navigator, click on the project name.

   3. From the Targets list in the Editor pane, click on your app.

   4. Click the Info tab.

   5. Expand Custom iOS Target Properties.

   6. Right-click on the list and select Add Row.

   7. From the dropdown menu, select Bonjour Services. This creates a new property list in the project directory called Info. This displays as Info.plist in the Finder.

2. Rename the Info.plist to Info-Debug.plist

   1. Click on Info file in the project list at the left.

   2. In the Identity and Type panel at the right, change the Name from Info.plist to Info-Debug.plist.

3. Create a Release property list.

   1. In the Project Navigator, click on Info-Debug.plist.

   2. Select File > Duplicate.... You can also press Cmd + Shift + S.

   3. In the dialog box, set the Save As: field to Info-Release.plist and click Save.

4. Add the necessary properties to the Debug property list.

   1. In the Project Navigator, click on Info-Debug.plist.

   2. Add the String value _dartVmService._tcp to the Bonjour Services array.

   3. (Optional) To set your desired customized permission dialog text, add the key Privacy - Local Network Usage Description.

      

5. Set the target to use different property lists for different build modes.

   1. In the Project Navigator, click on your project.

   2. Click the Build Settings tab.

   3. Click All and Combined sub-tabs.

   4. In the Search box, type plist. This limits the settings to those that include property lists.

   5. Scroll through the list until you see Packaging.

   6. Click on the Info.plist File setting.

   7. Change the Info.plist File value from path/to/Info.plist to path/to/Info-$(CONFIGURATION).plist.

      

      This resolves to the path Info-Debug.plist in Debug and Info-Release.plist in Release.

      

6. Remove the Release property list from the Build Phases.

   1. In the Project Navigator, click on your project.

   2. Click the Build Phases tab.

   3. Expand Copy Bundle Resources.

   4. If this list includes Info-Release.plist, click on it and then click the - (minus sign) under it to remove the property list from the resources list.

      

7. The first Flutter screen your Debug app loads prompts for local network permission.

   Click OK.

   (Optional) To grant permission before the app loads, enable Settings > Privacy > Local Network > Your App.

You can now add a Flutter screen to your existing iOS app.