---
title: CocoaPods manual installation
source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/installation/cocoapods-installation
---

We recommend that you use our [guided install](https://onenr.io/0qwLv87gkj5) to set up iOS monitoring. However, if you need to install the agent manually, follow the steps below to install the New Relic iOS agent with Cocoapods.

## Install your iOS application [#installation]

As part of the installation process, New Relic automatically generates an [application token](https://docs.newrelic.com/docs/mobile-apps/viewing-your-application-token). This is a 40-character hexadecimal string for authenticating each mobile app you monitor in New Relic.

To install and configure your iOS or tvOS application:

1.  Go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities)**.
2.  (If applicable) From the **Mobile Apps** list, select **Add a new app**.
3.  From the **Get Started** page, select **iOS** as the platform for mobile monitoring.
4.  Type a name for your mobile app, then select **Continue**.

Continue with the steps to configure New Relic for mobile monitoring.

## Configure using Objective-C [#objective-c]

These procedures to configure your iOS/tvOS app with CocoaPods and Objective-C also appear on the **Get Started** page in New Relic.

1.  In the `Podfile` for your project, add this line:

    ```ruby
    pod 'NewRelicAgent'
    ```

2.  Close your project in Xcode, then open your terminal and run this command in your project's directory:

    ```shell
    pod install
    ```

3.  Open your project in Xcode by running this command in the terminal:

    ```shell
    open App.xcworkspace
    ```

4.  In your `AppDelegate.m` file, add this New Relic header:

    ```objectivec
    #import <NewRelic/NewRelic.h>
    ```

5.  In your `AppDelegate.m` file, add this call as the first line of `application:didFinishLaunchingWithOptions`, replacing `APP_TOKEN` with your [application token](https://docs.newrelic.com/docs/mobile-apps/viewing-your-application-token):

    ```objectivec
    [NewRelic startWithApplicationToken:@"APP_TOKEN"];
    ```

    > #### ⚠️ IMPORTANT
    >
    > The agent must be on the first line of `didFinishLaunchingWithOptions` and run on the main thread to ensure proper instrumentation. Starting the call later, on a background thread, or asynchronously can cause unexpected or unstable behavior.

6.  Download this repo: <https://github.com/newrelic/newrelic-ios-agent-spm/archive/refs/heads/main.zip>.

7.  From the downloaded repo, copy `dsym-upload-tools` into the folder that contains your `xcodeproject` file. You should now have a folder containing these files:

    -   `YOUR_PROJECT.xcodeproj`
    -   `dsym-upload-tools/`

8.  Based on your iOS agent version, add the build script below to your target's **Build Phases**. Make sure the script is the very last build script, and replace `APP_TOKEN` with your [application token](https://docs.newrelic.com/docs/mobile-apps/viewing-your-application-token).
    -   For iOS agent 7.4.0 or higher:
        ```shell
        ARTIFACT_DIR="${BUILD_DIR%Build/*}"
        SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
        /bin/sh "${SCRIPT}" "APP_TOKEN"
        ```
        -   To write additional details to the upload_dsym_results.log file, add `--debug` as additional argument after the app token.
            ```shell
            ARTIFACT_DIR="${BUILD_DIR%Build/*}"
            SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
            /bin/sh "${SCRIPT}" "APP_TOKEN" --debug
            ```
    -   For iOS agent 7.3.8 or lower:
        ```shell
        SCRIPT=`/usr/bin/find "${SRCROOT}" -name newrelic_postbuild.sh | head -n 1`
        /bin/sh "${SCRIPT}" "APP_TOKEN"
        ```

9.  (Optional) Add the following lines to your build script above to skip symbol upload during debugging:

    ```shell
    if [ ${CONFIGURATION} = "Debug" ]; then
        echo "Skipping DSYM upload CONFIGURATION: ${CONFIGURATION}"
        exit 0
    fi
    ```

10. Clean and build your app, then run it in the simulator or on another device.

## Configure using Swift [#configuration]

These procedures to configure your iOS/tvOS app with CocoaPods and Swift also appear on the **Get Started** page in New Relic.

1.  In the **Podfile** for your project, add the following line:

    ```ruby
    pod 'NewRelicAgent'
    ```

2.  Close your project in Xcode, and update it by running this command from the terminal in your project directory:

    ```shell
    pod install
    ```

3.  Open your project in Xcode by running this command from the terminal in your project directory:

    ```shell
    open App.xcworkspace
    ```

4.  In your `AppDelegate.swift`, add the New Relic header:
    (If your app is written in SwiftUI, follow these [instructions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/troubleshoot/swiftui-appdelegate) to add an AppDelegate to your project.)

    ```swift
    import NewRelic
    ```

5.  In your `AppDelegate.swift` file, add this call as the first line of `application:didFinishLaunchingWithOptions`, replacing `APP_TOKEN` with your [application token](https://docs.newrelic.com/docs/mobile-apps/viewing-your-application-token):

    ```swift
    NewRelic.start(withApplicationToken:"APP_TOKEN")
    ```

    > #### ⚠️ IMPORTANT
    >
    > To ensure proper instrumentation, you must call the agent on the first line of `didFinishLaunchingWithOptions()`, and run the agent on the main thread. Starting the call later (on a background thread or asynchronously) can cause unexpected or unstable behavior.

6.  Download this repo: <https://github.com/newrelic/newrelic-ios-agent-spm/archive/refs/heads/main.zip>.

7.  From the downloaded repo, copy `dsym-upload-tools` into the folder that contains your `xcodeproject` file. You should now have a folder containing these files:

    -   `YOUR_PROJECT.xcodeproj`
    -   `dsym-upload-tools/`

8.  Based on your iOS agent version, add the build script below to your target's **Build Phases**. Make sure the script is the very last build script, and replace `APP_TOKEN` with your [application token](https://docs.newrelic.com/docs/mobile-apps/viewing-your-application-token).
    -   For iOS agent 7.4.0 or higher:
        ```shell
        ARTIFACT_DIR="${BUILD_DIR%Build/*}"
        SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
        /bin/sh "${SCRIPT}" "APP_TOKEN"
        ```
        -   To write additional details to the upload_dsym_results.log file, add '--debug' as additional argument after the app token.
            ```shell
            ARTIFACT_DIR="${BUILD_DIR%Build/*}"
            SCRIPT=`/usr/bin/find "${SRCROOT}" "${ARTIFACT_DIR}" -type f -name run-symbol-tool | head -n 1`
            /bin/sh "${SCRIPT}" "APP_TOKEN" --debug
            ```
    -   For iOS agent 7.3.8 or lower:
        ```shell
        SCRIPT=`/usr/bin/find "${SRCROOT}" -name newrelic_postbuild.sh | head -n 1`
        /bin/sh "${SCRIPT}" "APP_TOKEN"
        ```

9.  (Optional) Add the following lines to your build script above to skip symbol upload during debugging:

    ```shell
    if [ ${CONFIGURATION} = "Debug" ]; then
        echo "Skipping DSYM upload CONFIGURATION: ${CONFIGURATION}"
        exit 0
    fi
    ```

10. Clean and build your app, then run it in the simulator or on another device.

## (Optional) Change the logging level [#logging]

By default, the iOS agent logs at the `info` level. you can change the log level to collect more or less data. There are six supported log levels:

-   `none`
-   `error`
-   `warning`
-   `info`
-   `verbose`
-   `ALL`

> #### ⚠️ IMPORTANT
>
> Only increase the log level to `verbose` or higher for debugging, not for release builds.

To change the logging level in your app, add this method call before calling `NewRelic.start(withApplicationToken)`:

-   Objective-c:

    ```objectivec
    [NRLogger setLogLevels:NRLogLevelALL];
    ```

-   Swift:

    ```swift
    NRLogger.setLogLevels(NRLogLevelALL.rawValue)
    ```