Migrate the iOS agent from CocoaPods

CocoaPods has announced that its central registry (trunk) becomes permanently read-only on December 2, 2026. 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

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 and as an XCFramework download.
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.

Migrate your iOS app

Choose one of these installation methods:

Swift Package Manager: Apple's package manager, built into Xcode. You update the agent from Xcode.
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

Note which agent version you use today. It's listed next to NewRelicAgent in your Podfile.lock.

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:
bash
```
$pod deintegrate
```
If you still use other pods, delete the pod 'NewRelicAgent' line from your Podfile, then run:
bash
```
$pod install
```
Check that NewRelicAgent no longer appears in your Podfile.lock.

Open your project in Xcode. If you still use other pods, open the .xcworkspace file. Otherwise, open the .xcodeproj file.

Select File > Add Package Dependencies... and enter this URL:

https://github.com/newrelic/newrelic-ios-agent-spm

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

Add the NewRelic package product to your app target, and to any other target that used the pod, such as an app extension.

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.
Keep the script as the last build phase, and make sure Based on dependency analysis is unchecked.

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.

XCFramework

Close Xcode and remove the NewRelicAgent pod, as described in the Swift Package Manager steps.

Follow XCFramework manual installation to download the agent and add it to your app target. Make sure NewRelic.xcframework is set to Embed & Sign.

Check your dSYM upload build script as described in the Swift Package Manager steps. The 7.4.0 or higher script finds run-symbol-tool inside NewRelic.xcframework.

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.

Update your CI/CD pipelines

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:

bash

$xcodebuild -resolvePackageDependencies -project YourApp.xcodeproj -scheme YourApp

Migrate apps that use a hybrid agent

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	Turn on Swift Package Manager in your `Podfile`.
Flutter	Use Flutter's Swift Package Manager support, which is on by default from Flutter 3.44.
Ionic Capacitor	Move your iOS project to Swift Package Manager if it still uses CocoaPods.
Cordova	Update to `cordova-ios` 8 or higher.
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

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:

Update the React Native agent to version 1.9.3 or higher.

At the top of your ios/Podfile, add:

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

Run pod install in your ios directory, then check that NewRelicAgent no longer appears in your Podfile.lock.
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:

Update the React Native agent to version 1.9.3 or higher.
Install expo-build-properties:
bash
```
$npx expo install expo-build-properties
```

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

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

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

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, so most apps already get the iOS agent through it.

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

bash

$flutter config --enable-swift-package-manager

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

Ionic 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. It covers the npx cap spm-migration-assistant command and recreating the iOS platform.

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:

Update the Cordova agent to the latest version.
Update your iOS platform. See the cordova-ios 8 release announcement:
bash
```
$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.
Make sure your config.xml sets the iOS deployment target to 15.0 or higher:
```
<preference name="deployment-target" value="15.0" />
```
Build and run your app.

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. Make sure EDM4U doesn't also install the NewRelicAgent pod, so your app has only one copy of the agent.

Troubleshoot

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.

Before you migrate

Migrate your iOS app

Important

Swift Package Manager

XCFramework

Update your CI/CD pipelines

Migrate apps that use a hybrid agent

React Native

Standard React Native app

Expo app

Flutter

Ionic Capacitor

Cordova

Unity

Troubleshoot

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

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

I get duplicate symbol errors or warnings about classes implemented twice

Swift Package Manager reports a checksum or download error

Migrate the iOS agent from CocoaPods

Before you migrate .css-21sua1{background:none;border:none;width:0;padding:0;}

Migrate your iOS app

Important

Swift Package Manager

XCFramework

Update your CI/CD pipelines

Migrate apps that use a hybrid agent

React Native

Standard React Native app

Expo app

Flutter

Ionic Capacitor

Cordova

Unity

Troubleshoot

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

I get duplicate symbol errors or warnings about classes implemented twice

Swift Package Manager reports a checksum or download error

Before you migrate