# Integrate a Flutter module into your iOS project (Legacy)

> Learn how to integrate a Flutter module into your existing iOS project.



:::warning

As of Flutter 3.44, Swift Package Manager (SwiftPM) replaces CocoaPods
as the default dependency manager for iOS and macOS Flutter apps.
CocoaPods is officially in maintenance mode,
and its registry will permanently [become read-only on December 2, 2026][read-only].

This guide is preserved for reference only, and will not receive ongoing maintenance.
Please migrate to using Swift Package Manager using the [updated integration guide][].

:::

Flutter UI components can be incrementally added into your existing iOS
application as embedded frameworks.
To embed Flutter in your existing application,
consider one of the following three methods.

| Embedding Method | Methodology | Benefit |
|---|---|---|
| Use CocoaPods _(Recommended)_ | Install and use the Flutter SDK and CocoaPods. Flutter compiles the `flutter_module` from source each time Xcode builds the iOS app. | Least complicated method to embed Flutter into your app. |
| Use [iOS frameworks][] | Create iOS frameworks for Flutter components, embed them into your iOS, and update your existing app's build settings. | Doesn't require every developer to install the Flutter SDK and CocoaPods on their local machines. |
| Use iOS frameworks and CocoaPods | Embed the frameworks for your iOS app and the plugins in Xcode, but distribute the Flutter engine as a CocoaPods podspec. | Provides an alternative to distributing the large Flutter engine (`Flutter.xcframework`) library. |

{:.table .table-striped}

[iOS frameworks]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html

When you add Flutter to your existing iOS app,
it [increases the size of your iOS app][app-size].

For examples using an app built with UIKit,
see the iOS directories in the [add_to_app code samples][].
For an example using SwiftUI, consult the iOS directory in [News Feed App][].

## Development system requirements

Flutter requires the latest version of Xcode and [CocoaPods][].

## Create a Flutter module

To embed Flutter into your existing application with any method,
create a Flutter module first.
Use the following command to create a Flutter module.

```console
$ cd /path/to/my_flutter
$ flutter create --template module my_flutter
```

Flutter creates module project under `/path/to/my_flutter/`.
If you use the [CocoaPods method][], save the module
in the same parent directory as your existing iOS app.

[CocoaPods method]: /add-to-app/ios/project-setup-legacy/?tab=embed-using-cocoapods

From the Flutter module directory,
you can run the same `flutter` commands you would in any other Flutter project,
like `flutter run` or `flutter build ios`.
You can also run the module in [VS Code][] or
[Android Studio/IntelliJ][] with the Flutter and Dart plugins.
This project contains a single-view example version of your module
before embedding it in your existing iOS app.
This helps when testing the Flutter-only parts of your code.

## Organize your module

The `my_flutter` module directory structure resembles a typical Flutter app.

<FileTree>

- my_flutter/
  - .ios/
    - Runner.xcworkspace
    - Flutter/
      - podhelper.rb
  - lib/
    - main.dart
  - test/
  - pubspec.yaml

</FileTree>

Your Dart code should be added to the `lib/` directory.
Your Flutter dependencies, packages, and plugins must be added to the
`pubspec.yaml` file.

The `.ios/` hidden subfolder contains an Xcode workspace where
you can run a standalone version of your module.
This wrapper project bootstraps your Flutter code.
It contains helper scripts to facilitate building frameworks or
embedding the module into your existing application with CocoaPods.

:::note

* Add custom iOS code to your own existing application's
  project or to a plugin, not to the module's `.ios/`
  directory. Changes made in your module's `.ios/`
  directory don't appear in your existing iOS project
  using the module, and might be overwritten by Flutter.

* Exclude the `.ios/` directory from source control as
  it's autogenerated.

* Before building the module on a new machine,
  run `flutter pub get` in the `my_flutter` directory.
  This regenerates the `.ios/` directory before building
  the iOS project that uses the Flutter module.

:::

## Embed a Flutter module in your iOS app

After you have developed your Flutter module,
you can embed it using the methods described
in the table at the top of the page.

You can run in **Debug** mode on a simulator or a real device,
and **Release** mode on a real device.

:::note
Learn more about [Flutter's build modes][build modes of Flutter].

To use Flutter debugging features such as hot reload,
consult [Debugging your add-to-app module][].
:::

<Tabs key="darwin-deps">
<Tab name="Use CocoaPods">

### Use CocoaPods and the Flutter SDK {:#method-a .no_toc}

#### Approach {:#method-a-approach}

This first method uses CocoaPods to embed the Flutter modules.
CocoaPods manages dependencies for Swift projects,
including Flutter code and plugins.
Each time Xcode builds the app,
CocoaPods embeds the Flutter modules.

This allows rapid iteration with the most up-to-date
version of your Flutter module without running additional
commands outside of Xcode.

To learn more about CocoaPods,
consult the [CocoaPods getting started guide][].

#### Watch the video

If watching a video helps you learn,
this video covers adding Flutter to an iOS app:

<YouTubeEmbed id="IIcrfrTshTs" title="Step by step on how to add Flutter to an existing iOS app"></YouTubeEmbed>

#### Requirements {:#method-a-reqs}

Every developer working on your project must have a local version
of the Flutter SDK and CocoaPods installed.

#### Example project structure {:#method-a-structure}

This section assumes that your existing app and
the Flutter module reside in sibling directories.
If you have a different directory structure,
adjust the relative paths.
The example directory structure resembles the following:

<FileTree>

- my_flutter/
   - .ios/
   - Flutter/
      - podhelper.rb
- MyApp/
   - Podfile

</FileTree>

#### Update your Podfile

Add your Flutter modules to your Podfile configuration file.
This section presumes you called your Swift app `MyApp`.

1. _(Optional)_ If your existing app lacks a `Podfile` config file,
   navigate to the root of your app directory.
   Use the `pod init` command to create the `Podfile` file.

   :::tip
   If the `pod init` command errors,
   check that you're on the latest version of CocoaPods.
   :::

1. Update your `Podfile` config file.

   1. Add the following lines after the `platform` declaration.

      ```ruby title="MyApp/Podfile"
      flutter_application_path = '../my_flutter'
      load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')
      ```

   1. For each [Podfile target][] that needs to embed Flutter,
      add a call to the
      `install_all_flutter_pods(flutter_application_path)` method.
      Add these calls after the settings in the previous step.

      ```ruby title="MyApp/Podfile"
      target 'MyApp' do
        install_all_flutter_pods(flutter_application_path)
      end
      ```

   1. In the `Podfile`'s `post_install` block,
      add a call to `flutter_post_install(installer)`.
      This block should be the last block in the `Podfile` config file.

      ```ruby title="MyApp/Podfile"
      post_install do |installer|
        flutter_post_install(installer) if defined?(flutter_post_install)
      end
      ```

To review an example `Podfile`, consult this [Flutter Podfile sample][].

#### Embed your frameworks

At build time, Xcode packages your Dart code, each Flutter plugin,
and the Flutter engine into their own `*.xcframework` bundles.
CocoaPod's `podhelper.rb` script then embeds these
`*.xcframework` bundles into your project.

* `Flutter.xcframework` contains the Flutter engine.
* `App.xcframework` contains the compiled Dart code for this project.
* `<plugin>.xcframework` contains one Flutter plugin.

To embed the Flutter engine, your Dart code, and your Flutter plugins
into your iOS app, complete the following procedure.

1. Refresh your Flutter plugins.

   If you change the Flutter dependencies in the `pubspec.yaml` file,
   run `flutter pub get` in your Flutter module directory.
   This refreshes the list of plugins that the `podhelper.rb` script reads.

   ```console
   flutter pub get
   ```

1. Embed the plugins and frameworks with CocoaPods.

   1. Navigate to your iOS app project at `/path/to/MyApp/MyApp`.

   1. Use the `pod install` command.

      ```console
      pod install
      ```

   Your iOS app's **Debug** and **Release** build configurations embed
   the corresponding [Flutter components for that build mode][build-modes].

1. Build the project.

   1. Open `MyApp.xcworkspace` in Xcode.

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

   1. Select **Product** > **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

#### Set LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.
:::

1. Generate Flutter LLDB files.

   1. Within your flutter application, run the following:

   ```console
   flutter build ios --config-only
   ```

   This will generate the LLDB files in the `.ios/Flutter/ephemeral` directory.

1. Set the LLDB Init File.

   1. Go to **Product > Scheme > Edit Scheme**.

   1. Select the **Run** section in the left side bar.

   1. Set the **LLDB Init File** using the same relative path to your Flutter
      application as you put in your Podfile in the **Update your Podfile**
      section.

      ```console
      $(SRCROOT)/../my_flutter/.ios/Flutter/ephemeral/flutter_lldbinit
      ```

      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.

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      ```console
      command source --relative-to-command-file "../my_flutter/.ios/Flutter/ephemeral/flutter_lldbinit"
      ```

[build-modes]: /testing/build-modes
[CocoaPods getting started guide]: https://guides.cocoapods.org/using/using-cocoapods.html
[Podfile target]: https://guides.cocoapods.org/syntax/podfile.html#target
[Flutter Podfile sample]: https://github.com/flutter/samples/blob/main/add_to_app/plugin/ios_using_plugin/Podfile


</Tab>
<Tab name="Use frameworks">

### Link and Embed frameworks in Xcode {:#method-b .no_toc}

#### Approach {:#method-b-approach}

In this second method, edit your existing Xcode project,
generate the necessary frameworks, and embed them in your app.
Flutter generates iOS frameworks for Flutter itself,
for your compiled Dart code, and for each of your Flutter plugins.
Embed these frameworks and update your existing application's build settings.

#### Requirements {:#method-b-reqs}

No additional software or hardware requirements are needed for this method.
Use this method in the following use cases:

* Members of your team can't install the Flutter SDK and CocoaPods
* You don't want to use CocoaPods as a dependency manager in existing iOS apps

#### Limitations {:#method-b-limits}


Flutter can't handle [common dependencies with xcframeworks][common].
If both the host app and the Flutter module's plugin define the
same pod dependency and you integrate Flutter module using this option,
errors result.
These errors include issues like `Multiple commands produce
'CommonDependency.framework'`.

To work around this issue, link every plugin source in its `podspec` file
from the Flutter module to the host app's `Podfile`.
Link the source instead of the plugins' `xcframework` framework.
The next section explains how to [produce that framework][ios-framework].

To prevent the error that occurs when common dependencies exist,
use `flutter build ios-framework` with the `--no-plugins` flag.

[common]: https://github.com/flutter/flutter/issues/130220
[ios-framework]: https://github.com/flutter/flutter/issues/114692


#### Example project structure {:#method-b-structure}

The following example assumes that you want to generate the
frameworks to `/path/to/MyApp/Flutter/`.

```console
$ flutter build ios-framework --output=/path/to/MyApp/Flutter/
```

Run this _every time_ you change code in your Flutter module.

The resulting project structure should resemble this directory tree.

<FileTree>

- /path/to/MyApp/
  - Flutter/
    - Debug/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework (If you have plugins with iOS-platform code)
      - example_plugin.xcframework (One framework file for each plugin)
    - Profile/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework
    - Release/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework

</FileTree>

:::warning
Always use `Flutter.xcframework` and `App.xcframework` bundles
located in the same directory.
Mixing `.xcframework` imports from different directories
(like `Profile/Flutter.xcframework` with `Debug/App.xcframework`)
causes runtime crashes.
:::


#### Procedures

How you link, embed, or both the generated frameworks
into your existing app in Xcode depends on the type of framework.

* Link and embed dynamic frameworks.
* Link static frameworks. [Never embed them][static-framework].

Flutter plugins might produce [static or dynamic frameworks][].
Link static frameworks, [_never_ embed them][static-framework].

If you embed a static framework into your iOS app,
you can't publish that app to the App Store.
Publishing fails with a
`Found an unexpected Mach-O header code` archive error.

##### Link all frameworks

To link the necessary frameworks, follow this procedure.

1. Choose the frameworks to link.

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

   1. Click the **Build Phases** tab.

   1. Expand **Link Binary With Libraries**.

      <DashImage image="development/add-to-app/ios/project-setup/linked-libraries.png" caption="Expand the **Link Binary With Libraries** build phase in Xcode" />

   1. Click **+** (plus sign).

   1. Click **Add Other...** then **Add Files...**.

   1. From the **Choose frameworks and libraries to add:** dialog box,
      navigate to the `/path/to/MyApp/Flutter/Release/` directory.

   1. Command-click the frameworks in that directory then click **Open**.

      <DashImage image="development/add-to-app/ios/project-setup/choose-libraries.png" caption="Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" />

1. Update the paths to the libraries to account for build modes.

   1. Launch the Finder.

   1. Navigate to the `/path/to/MyApp/` directory.

   1. Right-click on `MyApp.xcodeproj` and select **Show Package
      Contents**.

   1. Open `project.pbxproj` with Xcode. The file opens in Xcode's text
      editor. This also locks **Project Navigator** until you close the text editor.

      <DashImage image="development/add-to-app/ios/project-setup/project-pbxproj.png" caption="The `project-pbxproj` file open in the Xcode text editor" />

   1. Find the lines that resemble the following text in the
      `/* Begin PBXFileReference section */`.

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = Flutter/[!Release!]/Flutter.xcframework;
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = Flutter/[!Release!]/App.xcframework;
        sourceTree = "<group>";
      };
      ```

   1. Change the `Release` text highlighted in the prior step
      and change it to `$(CONFIGURATION)`. Also wrap the path in
      quotation marks.

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/Flutter.xcframework[!"!];
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/App.xcframework[!"!];
        sourceTree = "<group>";
      };
      ```

1. Update the search paths.

   1. Click the **Build Settings** tab.

   1. Navigate to **Search Paths**

   1. Double-click to the right of **Framework Search Paths**.

   1. In the combo box, click **+** (plus sign).

   1. Type `$(inherited)`.
      and press <kbd>Enter</kbd>.

   1. Click **+** (plus sign).

   1. Type `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`
      and press <kbd>Enter</kbd>.

      <DashImage image="development/add-to-app/ios/project-setup/framework-search-paths.png" caption="Update **Framework Search Paths** in Xcode" />

After linking the frameworks, they should display in the
**Frameworks, Libraries, and Embedded Content**
section of your target's **General** settings.

##### Embed the dynamic frameworks

To embed your dynamic frameworks, complete the following procedure.

1. Navigate to **General** <span aria-label="and then">></span>
   **Frameworks, Libraries, and Embedded Content**.

1. Click on each of your dynamic frameworks and select **Embed & Sign**.

   <DashImage image="development/add-to-app/ios/project-setup/choose-to-embed.png" caption="Select **Embed & Sign** for each of your frameworks in Xcode" />

   Don't include any static frameworks,
   including `FlutterPluginRegistrant.xcframework`.

1. Click the **Build Phases** tab.

1. Expand **Embed Frameworks**.
   Your dynamic frameworks should display in that section.

   <DashImage image="development/add-to-app/ios/project-setup/embed-xcode.png" caption="The expanded **Embed Frameworks** build phase in Xcode" />

1. Build the project.

   1. Open `MyApp.xcworkspace` in Xcode.

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

   1. Select **Product** <span aria-label="and then">></span>
      **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

#### Set LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.
:::

1. Generate Flutter LLDB files.

   1. Within your flutter application, re-run `flutter build ios-framework` if
      you haven't already:

   ```console
   $ flutter build ios-framework --output=/path/to/MyApp/Flutter/
   ```

   This will generate the LLDB files in the `/path/to/MyApp/Flutter/` directory.

1. Set the LLDB Init File.

   1. Go to **Product > Scheme > Edit Scheme**.

   1. Select the **Run** section in the left side bar.

   1. Set the **LLDB Init File** to the following:

      ```console
      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      ```

      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.

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      ```console
      command source --relative-to-command-file "Flutter/flutter_lldbinit"
      ```

[static or dynamic frameworks]: https://stackoverflow.com/questions/32591878/ios-is-it-a-static-or-a-dynamic-framework
[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html


[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html


</Tab>
<Tab name="Use frameworks and CocoaPods">

### Use frameworks in Xcode and Flutter framework as podspec {:#method-c .no_toc}

#### Approach {:#method-c-approach}

This method generates Flutter as a CocoaPods podspec instead of
distributing the large `Flutter.xcframework` to other developers,
machines, or continuous integration systems.
Flutter still generates iOS frameworks for your compiled Dart code,
and for each of your Flutter plugins.
Embed these frameworks and update your existing application's build settings.

#### Requirements {:#method-c-reqs}

No additional software or hardware requirements are needed for this method.
Use this method in the following use cases:

* Members of your team can't install the Flutter SDK and CocoaPods
* You don't want to use CocoaPods as a dependency manager in existing iOS apps

#### Limitations {:#method-c-limits}


Flutter can't handle [common dependencies with xcframeworks][common].
If both the host app and the Flutter module's plugin define the
same pod dependency and you integrate Flutter module using this option,
errors result.
These errors include issues like `Multiple commands produce
'CommonDependency.framework'`.

To work around this issue, link every plugin source in its `podspec` file
from the Flutter module to the host app's `Podfile`.
Link the source instead of the plugins' `xcframework` framework.
The next section explains how to [produce that framework][ios-framework].

To prevent the error that occurs when common dependencies exist,
use `flutter build ios-framework` with the `--no-plugins` flag.

[common]: https://github.com/flutter/flutter/issues/130220
[ios-framework]: https://github.com/flutter/flutter/issues/114692


This method only works with the `beta` or `stable` [release channels][].

[release channels]: /install/upgrade#switching-flutter-channels

#### Example project structure {:#method-c-structure}

The following example assumes that you want to generate the
frameworks to `/path/to/MyApp/Flutter/`.

```console
$ flutter build ios-framework --output=/path/to/MyApp/Flutter/
```

Run this _every time_ you change code in your Flutter module.

The resulting project structure should resemble this directory tree.

<FileTree>

- /path/to/MyApp/
  - Flutter/
    - Debug/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework (If you have plugins with iOS-platform code)
      - example_plugin.xcframework (One framework file for each plugin)
    - Profile/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework
    - Release/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework

</FileTree>

:::warning
Always use `Flutter.xcframework` and `App.xcframework` bundles
located in the same directory.
Mixing `.xcframework` imports from different directories
(like `Profile/Flutter.xcframework` with `Debug/App.xcframework`)
causes runtime crashes.
:::


#### Add Flutter engine to your Podfile

Host apps using CocoaPods can add the Flutter engine to their Podfile.

```ruby title="MyApp/Podfile"
pod 'Flutter', :podspec => '/path/to/MyApp/Flutter/[![build mode]!]/Flutter.podspec'
```

:::note
You must hard code the `[build mode]` value.
For example, use `Debug` if you need to use `flutter attach`
and `Release` when you're ready to ship.
:::

#### Link and embed app and plugin frameworks

Flutter plugins might produce [static or dynamic frameworks][].
Link static frameworks, [_never_ embed them][static-framework].

If you embed a static framework into your iOS app,
you can't publish that app to the App Store.
Publishing fails with a
`Found an unexpected Mach-O header code` archive error.

##### Link all frameworks

To link the necessary frameworks, follow this procedure.

1. Choose the frameworks to link.

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

   1. Click the **Build Phases** tab.

   1. Expand **Link Binary With Libraries**.

      <DashImage image="development/add-to-app/ios/project-setup/linked-libraries.png" caption="Expand the **Link Binary With Libraries** build phase in Xcode" />

   1. Click **+** (plus sign).

   1. Click **Add Other...** then **Add Files...**.

   1. From the **Choose frameworks and libraries to add:** dialog box,
      navigate to the `/path/to/MyApp/Flutter/Release/` directory.

   1. Command-click the frameworks in that directory then click **Open**.

      <DashImage image="development/add-to-app/ios/project-setup/choose-libraries.png" caption="Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" />

1. Update the paths to the libraries to account for build modes.

   1. Launch the Finder.

   1. Navigate to the `/path/to/MyApp/` directory.

   1. Right-click on `MyApp.xcodeproj` and select **Show Package
      Contents**.

   1. Open `project.pbxproj` with Xcode. The file opens in Xcode's text
      editor. This also locks **Project Navigator** until you close the text editor.

      <DashImage image="development/add-to-app/ios/project-setup/project-pbxproj.png" caption="The `project-pbxproj` file open in the Xcode text editor" />

   1. Find the lines that resemble the following text in the
      `/* Begin PBXFileReference section */`.

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = Flutter/[!Release!]/Flutter.xcframework;
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = Flutter/[!Release!]/App.xcframework;
        sourceTree = "<group>";
      };
      ```

   1. Change the `Release` text highlighted in the prior step
      and change it to `$(CONFIGURATION)`. Also wrap the path in
      quotation marks.

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/Flutter.xcframework[!"!];
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/App.xcframework[!"!];
        sourceTree = "<group>";
      };
      ```

1. Update the search paths.

   1. Click the **Build Settings** tab.

   1. Navigate to **Search Paths**

   1. Double-click to the right of **Framework Search Paths**.

   1. In the combo box, click **+** (plus sign).

   1. Type `$(inherited)`.
      and press <kbd>Enter</kbd>.

   1. Click **+** (plus sign).

   1. Type `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`
      and press <kbd>Enter</kbd>.

      <DashImage image="development/add-to-app/ios/project-setup/framework-search-paths.png" caption="Update **Framework Search Paths** in Xcode" />

After linking the frameworks, they should display in the
**Frameworks, Libraries, and Embedded Content**
section of your target's **General** settings.

##### Embed the dynamic frameworks

To embed your dynamic frameworks, complete the following procedure.

1. Navigate to **General** <span aria-label="and then">></span>
   **Frameworks, Libraries, and Embedded Content**.

1. Click on each of your dynamic frameworks and select **Embed & Sign**.

   <DashImage image="development/add-to-app/ios/project-setup/choose-to-embed.png" caption="Select **Embed & Sign** for each of your frameworks in Xcode" />

   Don't include any static frameworks,
   including `FlutterPluginRegistrant.xcframework`.

1. Click the **Build Phases** tab.

1. Expand **Embed Frameworks**.
   Your dynamic frameworks should display in that section.

   <DashImage image="development/add-to-app/ios/project-setup/embed-xcode.png" caption="The expanded **Embed Frameworks** build phase in Xcode" />

1. Build the project.

   1. Open `MyApp.xcworkspace` in Xcode.

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

   1. Select **Product** <span aria-label="and then">></span>
      **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

#### Set LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.
:::

1. Generate Flutter LLDB files.

   1. Within your flutter application, re-run `flutter build ios-framework` if
      you haven't already:

   ```console
   $ flutter build ios-framework --output=/path/to/MyApp/Flutter/
   ```

   This will generate the LLDB files in the `/path/to/MyApp/Flutter/` directory.

1. Set the LLDB Init File.

   1. Go to **Product > Scheme > Edit Scheme**.

   1. Select the **Run** section in the left side bar.

   1. Set the **LLDB Init File** to the following:

      ```console
      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      ```

      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.

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      ```console
      command source --relative-to-command-file "Flutter/flutter_lldbinit"
      ```

[static or dynamic frameworks]: https://stackoverflow.com/questions/32591878/ios-is-it-a-static-or-a-dynamic-framework
[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html



</Tab>
</Tabs>


## Set local network privacy permissions

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

:::warning
Never enable this service in the **Release** version of your app.
The Apple App Store might reject your app.
:::

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.

   1. In the **Project Navigator**, click on the project name.

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

   1. Click the **Info** tab.

   1. Expand **Custom iOS Target Properties**.

   1. Right-click on the list and select **Add Row**.

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

1. Rename the `Info.plist` to `Info-Debug.plist`

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

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

1. Create a Release property list.

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

   1. Select **File** > **Duplicate...**.
      You can also press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd>.

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

1. Add the necessary properties to the **Debug** property list.

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

   1. Add the String value `_dartVmService._tcp`
      to the **Bonjour Services** array.

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

      <DashImage image="development/add-to-app/ios/project-setup/debug-plist.png" caption="The `Info-Debug` property list with the **Bonjour Services** and **Privacy - Local Network Usage Description** keys added" />

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

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

   1. Click the **Build Settings** tab.

   1. Click **All** and **Combined** sub-tabs.

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

   1. Scroll through the list until you see **Packaging**.

   1. Click on the **Info.plist File** setting.

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

      <DashImage image="development/add-to-app/ios/project-setup/set-plist-build-setting.png" caption="Updating the `Info.plist` build setting to use build mode-specific property lists" />

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

      <DashImage image="development/add-to-app/ios/project-setup/plist-build-setting.png" caption="The updated **Info.plist File** build setting displaying the configuration variations" />

1. Remove the **Release** property list from the **Build Phases**.

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

   1. Click the **Build Phases** tab.

   1. Expand **Copy Bundle Resources**.

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

      <DashImage image="development/add-to-app/ios/project-setup/copy-bundle.png" caption="The **Copy Bundle** build phase displaying the **Info-Release.plist** setting. Remove this setting." />

1. 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**.

[debugging functionalities such as hot-reload and DevTools]: /add-to-app/debugging

## Mitigate known issue with Apple Silicon Macs

On [Macs running Apple Silicon][apple-silicon],
the host app builds for an `arm64` simulator.
While Flutter supports `arm64` simulators, some plugins might not.
If you use one of these plugins, you might see a compilation error like
**Undefined symbols for architecture arm64**.
If this occurs,
exclude `arm64` from the simulator architectures in your host app.

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

1. Click the **Build Settings** tab.

1. Click **All** and **Combined** sub-tabs.

1. Under **Architectures**, click on **Excluded Architectures**.

1. Expand to see the available build configurations.

1. Click **Debug**.

1. Click the **+** (plus sign).

1. Select **iOS Simulator**.

1. Double-click in the value column for **Any iOS Simulator SDK**.

1. Click the **+** (plus sign).

1. Type `arm64` in the **Debug > Any iOS Simulator SDK** dialog box.

   <DashImage image="development/add-to-app/ios/project-setup/excluded-archs.png" caption="Add `arm64` as an excluded architecture for your app" />

1. Press <kbd>Esc</kbd> to close this dialog box.

1. Repeat these steps for the **Release** build mode.

1. Repeat for any iOS unit test targets.

## Next steps

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

[add_to_app code samples]: https://github.com/flutter/samples/tree/main/add_to_app
[add a Flutter screen]: /add-to-app/ios/add-flutter-screen
[Android Studio/IntelliJ]: /tools/android-studio
[build modes of Flutter]: /testing/build-modes
[CocoaPods]: https://cocoapods.org/
[app-size]: /resources/faq#how-big-is-the-flutter-engine
[VS Code]: /tools/vs-code
[News Feed app]: https://github.com/flutter/put-flutter-to-work/tree/022208184ec2623af2d113d13d90e8e1ce722365
[Debugging your add-to-app module]: /add-to-app/debugging/
[apple-silicon]: https://support.apple.com/en-us/116943
[read-only]: https://blog.cocoapods.org/CocoaPods-Specs-Repo/
[updated integration guide]: /add-to-app/ios/project-setup