---
title: Migrate the iOS agent from CocoaPods
source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/migrate-from-cocoapods
---

CocoaPods has announced that its central registry (trunk) [becomes permanently read-only on December 2, 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/). After that date, CocoaPods stops accepting new pod versions. This page explains what that means for the New Relic iOS agent and the hybrid agents built on it, and how to move your app to another installation method.

## Before you migrate [#before-you-migrate]

Review these answers before you migrate:

-   **What's changing?** Version **7.7.10** is the last iOS agent we publish to CocoaPods (the `NewRelicAgent` pod). Later versions are available only through [Swift Package Manager](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/spm-installation) and as an [XCFramework download](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/xcframework-installation).
-   **Will my app break?** No. Every `NewRelicAgent` version already published stays on CocoaPods, so `pod install` and your CI pipelines keep working. You just don't get newer agent versions through CocoaPods.
-   **Why migrate?** To keep receiving new features, fixes, and support for new iOS and Xcode versions, move to Swift Package Manager or the XCFramework.

This change also affects the hybrid agents that get the iOS agent through CocoaPods. If you use React Native, Flutter, Ionic Capacitor, Cordova, or Unity, see [Migrate apps that use a hybrid agent](#hybrid).

## Migrate your iOS app [#ios]

Choose one of these installation methods:

-   [Swift Package Manager](#spm): Apple's package manager, built into Xcode. You update the agent from Xcode.
-   [XCFramework](#xcframework): A framework bundle you download and add to your project yourself. You update it by downloading a new version.

The iOS agent doesn't depend on any other package, so you can move it to Swift Package Manager even if some of your other dependencies stay on CocoaPods for now. If you plan to move all your dependencies off CocoaPods, check that each of them supports Swift Package Manager first. For a dependency that doesn't, the XCFramework method lets you add and update the agent independently of any package manager.

> #### ⚠️ IMPORTANT
>
> Install the agent with only one method. If the `NewRelicAgent` pod is still installed when you add the agent another way, your app ends up with two copies of the agent, which causes build errors or unpredictable behavior.

### Swift Package Manager [#spm]

1.  Note which agent version you use today. It's listed next to `NewRelicAgent` in your `Podfile.lock`.
2.  Close Xcode, then remove the `NewRelicAgent` pod:
    -   If `NewRelicAgent` is your only pod, run this command in your project's directory, then delete your `Podfile`, `Podfile.lock`, and the `.xcworkspace` file that CocoaPods generated:

        ```shell
        pod deintegrate
        ```

    -   If you still use other pods, delete the `pod 'NewRelicAgent'` line from your `Podfile`, then run:

        ```shell
        pod install
        ```

        Check that `NewRelicAgent` no longer appears in your `Podfile.lock`.
3.  Open your project in Xcode. If you still use other pods, open the `.xcworkspace` file. Otherwise, open the `.xcodeproj` file.
4.  Select **File > Add Package Dependencies...** and enter this URL:
    ````
    https://github.com/newrelic/newrelic-ios-agent-spm
    ```

    For the dependency rule, choose <DNT>**Up to Next Major Version**</DNT>, starting from the version you noted in the first step or a newer one.

    ````
5.  Add the **NewRelic** package product to your app target, and to any other target that used the pod, such as an app extension.
6.  Check your dSYM upload build script in your target's **Build Phases**:
    -   If it's the script for iOS agent 7.4.0 or higher (it searches for `run-symbol-tool`), keep it as is. It finds the tool in the Swift package.
    -   If it calls `newrelic_postbuild.sh`, or uses a path inside `Pods/`, replace it with the 7.4.0 or higher script from [Swift Package Manager installation](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/spm-installation).

        Keep the script as the last build phase, and make sure **Based on dependency analysis** is unchecked.
7.  Clean and build your app, then run it. The code that starts the agent and your application token don't change.

To update the agent later, see [Update with Swift Package Manager](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/upgrade-ios-agent#SPM).

### XCFramework [#xcframework]

1.  Close Xcode and remove the `NewRelicAgent` pod, as described in the [Swift Package Manager steps](#spm).
2.  Follow [XCFramework manual installation](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/xcframework-installation) to download the agent and add it to your app target. Make sure `NewRelic.xcframework` is set to **Embed & Sign**.
3.  Check your dSYM upload build script as described in the [Swift Package Manager steps](#spm). The 7.4.0 or higher script finds `run-symbol-tool` inside `NewRelic.xcframework`.
4.  Clean and build your app, then run it. The code that starts the agent and your application token don't change.

To update the agent later, see [Manually replace your iOS agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/upgrade-ios-agent#Manual).

### Update your CI/CD pipelines [#ci]

If you removed CocoaPods completely, update any pipeline steps that run `pod install` or build the `.xcworkspace` file. If you use Swift Package Manager, consider resolving packages in a separate step before the build:

```shell
xcodebuild -resolvePackageDependencies -project YourApp.xcodeproj -scheme YourApp
```

## Migrate apps that use a hybrid agent [#hybrid]

Hybrid agents include the iOS agent for you. Most of them can get it through CocoaPods or Swift Package Manager, and your app's project setup decides which one is used:

| Agent                         | What to do                                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| [React Native](#react-native) | Turn on Swift Package Manager in your `Podfile`.                                                         |
| [Flutter](#flutter)           | Use Flutter's Swift Package Manager support, which is on by default from Flutter 3.44.                   |
| [Ionic Capacitor](#capacitor) | Move your iOS project to Swift Package Manager if it still uses CocoaPods.                               |
| [Cordova](#cordova)           | Update to `cordova-ios` 8 or higher.                                                                     |
| [Unity](#unity)               | No action required. To get newer iOS agent versions, add the XCFramework to your Xcode project yourself. |
| .NET MAUI and Unreal Engine   | No action required. These agents include the iOS agent in their own package and don't use CocoaPods.     |

If your app keeps getting the iOS agent through CocoaPods, you can still update your hybrid agent. New hybrid agent versions keep iOS agent **7.7.10** for CocoaPods and use newer iOS agent versions only through Swift Package Manager.

### React Native [#react-native]

By default, the React Native agent gets the iOS agent from CocoaPods. You can switch to Swift Package Manager with React Native agent 1.9.3 or higher.

#### Standard React Native app

Before you switch, make sure your app meets these requirements:

-   React Native 0.75 or higher
-   `use_frameworks! :linkage => :dynamic` in your `Podfile`
-   A `post_install` block in your `Podfile` that calls `react_native_post_install`, as the standard React Native template does

To switch, follow these steps:

1.  Update the React Native agent to version 1.9.3 or higher.

2.  At the top of your `ios/Podfile`, add:

    ```ruby
    ENV['NEWRELIC_USE_SPM'] = '1'
    use_frameworks! :linkage => :dynamic
    ```

3.  Run `pod install` in your `ios` directory, then check that `NewRelicAgent` no longer appears in your `Podfile.lock`.

4.  Build and run your app.

#### Expo app

`npx expo prebuild` regenerates your `ios` folder, so set this up in your project configuration instead of in the `Podfile`. You need Expo SDK 52 or higher.

To switch, follow these steps:

1.  Update the React Native agent to version 1.9.3 or higher.

2.  Install `expo-build-properties`:

    ```shell
    npx expo install expo-build-properties
    ```

3.  In your `app.json` or `app.config.js`, set iOS to use dynamic frameworks:

    ```json
    "plugins": [
      "newrelic-react-native-agent",
      ["expo-build-properties", { "ios": { "useFrameworks": "dynamic" } }]
    ]
    ```

4.  Add `NEWRELIC_USE_SPM=1` to the `.env` file in your project's root directory. `npx expo prebuild` and `npx expo run:ios` load it.

5.  Run `npx expo prebuild --clean`, then check that `NewRelicAgent` no longer appears in `ios/Podfile.lock`.

If `NEWRELIC_USE_SPM` isn't set when CocoaPods runs, for example when you run `pod install` or `npx pod-install` yourself, your app goes back to getting the iOS agent from CocoaPods.

### Flutter [#flutter]

The Flutter agent supports both CocoaPods and Swift Package Manager, and Flutter decides which one to use. From Flutter 3.44, [Swift Package Manager is on by default](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers), so most apps already get the iOS agent through it.

If you turned Swift Package Manager off, turn it back on by running:

```shell
flutter config --enable-swift-package-manager
```

Also remove `enable-swift-package-manager: false` from your `pubspec.yaml` if you added it.

### Ionic Capacitor [#capacitor]

The Capacitor agent supports both CocoaPods and Swift Package Manager, and your iOS project decides which one is used. Capacitor 8 creates new iOS projects with Swift Package Manager, but a project created with CocoaPods keeps using it until you migrate it.

-   If your `ios/App` folder has a `CapApp-SPM` package, you already use Swift Package Manager. `npx cap sync` keeps the agent up to date.
-   If it has a `Podfile`, move your project to Swift Package Manager by following [Capacitor's Swift Package Manager guide](https://capacitorjs.com/docs/ios/spm). It covers the `npx cap spm-migration-assistant` command and recreating the iOS platform.

### Cordova [#cordova]

With `cordova-ios` 8 or higher, the Cordova agent gets the iOS agent through Swift Package Manager. Earlier `cordova-ios` versions use CocoaPods.

To migrate, follow these steps:

1.  Update the Cordova agent to the latest version.

2.  Update your iOS platform. See the [cordova-ios 8 release announcement](https://cordova.apache.org/announcements/2025/11/23/cordova-ios-8.0.0.html):

    ```shell
    cordova platform remove ios
    cordova platform add ios@8
    ```

    Removing the platform deletes the `platforms/ios` folder, so you lose any changes you made there by hand. Back them up first.

3.  Make sure your `config.xml` sets the iOS deployment target to 15.0 or higher:

    ```xml
    <preference name="deployment-target" value="15.0" />
    ```

4.  Build and run your app.

### Unity [#unity]

The Unity agent gets the iOS agent through CocoaPods, using the External Dependency Manager for Unity (EDM4U). It doesn't support Swift Package Manager. Your app keeps building with the versions already on CocoaPods, and new Unity agent versions keep iOS agent **7.7.10**.

To use a newer iOS agent version, add the XCFramework to your Xcode project yourself, as described in the Unity agent's [dependency steps](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-unity/monitor-your-unity-application#manage-dependencies). Make sure EDM4U doesn't also install the `NewRelicAgent` pod, so your app has only one copy of the agent.

## Troubleshoot [#troubleshooting]

**My build fails with 'No such module NewRelic' after migrating to Swift Package Manager**

Make sure the **NewRelic** package product is added to the target that fails to build. In your target's settings, check the **Frameworks, Libraries, and Embedded Content** section. If your project has several targets, add the product to each one that uses the agent.

**My app crashes at launch with 'Library not loaded: @rpath/NewRelic.framework/NewRelic'**

The agent is linked but not embedded in your app:

-   Swift Package Manager: Add the **NewRelic** package product to your app target itself, not only to a framework or extension target.
-   XCFramework: In your app target's **Frameworks, Libraries, and Embedded Content** section, set `NewRelic.xcframework` to **Embed & Sign**.

    If you use a hybrid agent, see the steps for your agent in [Migrate apps that use a hybrid agent](#hybrid).

**I get duplicate symbol errors or warnings about classes implemented twice**

Your app has two copies of the agent. Check that `NewRelicAgent` no longer appears in your `Podfile.lock`, and that you added the agent with only one method.

**Swift Package Manager reports a checksum or download error**

See the [Swift Package Manager troubleshooting steps](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/spm-installation#troubleshooting).