> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/navigation/v2/llms.txt)

# Installation

Before starting to develop your application with the Navigation SDK, you'll need to configure your credentials and add the SDK as a dependency.

## Part 1: Create and configure your credentials

To download and install the SDK, follow the steps below. Start by logging into your Mapbox account, then create and configure a secret access token, and lastly add your public access token to your `Info.plist`.

### Step 1: Log in/Sign up for a Mapbox account

Login to your [Mapbox account](https://console.mapbox.com/). If you don't have an account, [sign up for free here](https://account.mapbox.com/auth/signup/).

Your account includes a [default public access token](https://docs.mapbox.com/accounts/guides/tokens/#default-public-access-token), and allows you to create a secret access token for use in the installation of the SDK.

### Step 2: Create a secret token

A secret access token can enable access to various products/services at Mapbox, including the ability to download an SDK. To allow download access to an SDK, follow these steps:

1.  From your account's [tokens page](https://console.mapbox.com/account/access-tokens/), click the **Create a token** button.
2.  From the token creation page, give your token a name and make sure the box next to the `Downloads:Read` scope is checked.
3.  Click the **Create token** button at the bottom of the page to create your token.
4.  The token you've created is a *secret token*, which means you will only have one opportunity to copy it somewhere secure.

> **Note (warning): Protect secret access tokens**
> 
> Store secret tokens in secure a location, outside of your project folder to make sure unauthorized users cannot find it.

### Step 3: Configure your secret token

Your secret access token is used only when downloading the SDK binaries for use in your project.

To use your secret token, you must store it in a `.netrc` file in your home directory (not your project folder). This approach helps avoid accidentally exposing your secret token by keeping it out of your application's source code.

To create a `.netrc` file follow these steps:

**Step 3-1:** Check if you have already created a `.netrc` file on your computer.

1.  In a terminal, go to your home directory.

```bash
$ cd ~
```

2.  Run `file .netrc` to check whether a `.netrc` file already exists. You will see the following message if there is no `.netrc` file:

```bash
$ file .netrc
.netrc: cannot open `.netrc' (No such file or directory)
```

3.  If you already have a `.netrc` file, skip the next step.

**Step 3-2:** Create the `.netrc` file.

-   From the same terminal, run `touch .netrc`.

**Step 3-3:** Open the `.netrc` file.

-   From the same terminal, run `open .netrc`.

**Step 3-4:** Add Mapbox credentials to the `.netrc` file

Add the following lines of text to your `.netrc` file, replacing `<INSERT SECRET ACCESS TOKEN>` with the secret access token you created in step 2:

```bash
machine api.mapbox.com
login mapbox
password <INSERT SECRET ACCESS TOKEN>
```

**Step 3-5:** Set `.netrc` file permissions to Read & Write for the current user

**Finder**

1.  Go to your home directory: `/Users/[CurrentUser]`.

-   If you do not see the `.netrc` file, press `Command` + `Shift` + `.` (the period key).

2.  Right click on the `.netrc`.
3.  Click `Get Info`.
4.  Scroll down to `Sharing & Permissions`.
5.  Under your current username, make sure to set `Privilege` to `Read & Write`.

**Terminal**

From the same terminal, run `chmod -R 0600 .netrc`

### Step 4: Configure your public token

Your public access token is used in your application code when requesting Mapbox resources.

To configure your public access token, follow these steps:

1.  Open your project's `Info.plist` file
2.  Hover over a key and click the plus button
3.  Type `MBXAccessToken` into the key field
4.  Click the value field and paste in your public access token.

> **Note: Rotating Tokens**
> 
> When you need to [rotate your access token](https://docs.mapbox.com/help/how-mapbox-works/access-tokens/), you will need to update the token value in your `Info.plist` file.

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/ios/ios/assets/medias/MapsInstallPublicToken-eb2f6fbf8715def5ae8eaa35a5b562c4.mp4).

> **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/dive-deeper/private-access-token-android-and-ios/)**
> 
> Learn how to keep access tokens private in mobile apps.

## Part 2: Add the dependency

Users expect the SDK to continue to track the user's location and deliver audible instructions even while a different application is visible or the device is locked. To do this, go to the Signing & Capabilities tab. Under the Background Modes section, enable "Audio, AirPlay, and Picture in Picture" and "Location updates". (Or, add the `audio` and `location` values to the `UIBackgroundModes` array in the `Info` tab.)

> **Note: Installing MapboxNavigation versus MapboxCoreNavigation**
> 
> `MapboxCoreNavigation` is a dependency of `MapboxNavigation`. If you install `MapboxNavigation` you will also have access to all `MapboxCoreNavigation`'s classes and methods. If you do not plan to use the [drop-in UI](https://docs.mapbox.com/ios/navigation/v2/guides/turn-by-turn-navigation/user-interface/#use-the-drop-in-ui), you can replace `MapboxNavigation` with `MapboxCoreNavigation` in your Podfile or when selecting a library in Swift Package Manager.

Mapbox provides the Navigation SDK via **CocoaPods** and **Swift Package Manager**.

**Swift Package Manager**

The Mapbox Navigation SDK can be consumed via Swift Package Manager (SPM). To add the Navigation SDK with SPM, you will need to configure your environment to download it from Mapbox. This requires a Mapbox access token with the `Downloads:Read` scope. In a previous step, you added this token to your `.netrc` file.

You can add the dependency to either an application or another package.

### Option 1: Add to an application

1.  Open your Xcode project or workspace, then go to **File** > > **Add Packages**.
2.  Enter `https://github.com/mapbox/mapbox-navigation-ios.git` as the URL and press `Enter` to pull in the package.
3.  Set **Dependency Rule** to **Up to Next Major Version** and enter `2.21.0` as the minimum version. Click **Add Package**.
4.  Once Xcode finishes fetching and checking out all the dependencies, select the **MapboxNavigation** library (or **MapboxCoreNavigation** if you don't need any UI components). Click **Next**.
5.  In your code, you can now `import MapboxNavigation` as well as any of the other packages that were downloaded as dependencies.

### Option 2: Add to an another package

To install the MapboxNavigation framework in another package rather than in an application, run `swift package init` to create a Package.swift, or click **File > New > Package**. Then, add the following dependency:

```swift
.package(name: "MapboxNavigation", url: "https://github.com/mapbox/mapbox-navigation-ios.git", from: "2.21.0")
```

**Notes**

-   If you need to update your packages, you can click on **File** > **Swift Packages** > **Update To Latest Package Versions**.
-   Sometimes, artifacts cannot be resolved or errors can occur, in this case select **File** > **Swift Packages** > **Reset Package Cache**.
-   If your Xcode crashes, delete your derived data folder.

**CocoaPods**

To add the Mapbox Navigation SDK dependency with CocoaPods, you will need to configure your build to download the Navigation SDK from Mapbox directly. This requires a valid username and an access token with the `Downloads: Read` scope. In a previous step, you added these items to your `.netrc` file.

1.  Create a [Podfile](https://guides.cocoapods.org/syntax/podfile.html) with the following specification:

```ruby
use_frameworks!
target 'TargetNameForYourApp' do
  pod 'MapboxNavigation', '~> 2.21.0.majorMinor'
end
```

2.  Run `pod repo update && pod install` and open the resulting Xcode workspace.

**Carthage**

MapboxNavigation no longer supports Carthage as of v2. But if you are building a user interface from scratch, you can install the MapboxCoreNavigation framework using Carthage.

To install the MapboxCoreNavigation framework using [Carthage](https://github.com/Carthage/Carthage/) v0.38 or above:

1.  *(Optional)* Clear your Carthage caches:

```bash
rm -rf ~/Library/Caches/carthage/ ~/Library/Caches/org.carthage.CarthageKit/binaries/{MapboxCommon-ios,MapboxNavigationNative,mapbox-ios-sdk-dynamic}
```

2.  Create a [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#github-repositories) with the following dependency:

```cartfile
github "mapbox/mapbox-navigation-ios" ~> "2.21.0"
```

3.  Run

```bash
carthage bootstrap --platform iOS --use-xcframeworks --cache-builds --use-netrc
```

4.  Follow the rest of [Carthage's iOS integration instructions](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). Your application target's Embed Frameworks build phase should include `MapboxCoreNavigation.xcframework`, `MapboxNavigationNative.xcframework`, and `MapboxCommon.xcframework`.

> **Note (warning): Using Carthage bootstrap**
> 
> Always use the --use-netrc flag when running carthage bootstrap.

> **Related content (troubleshooting): [Running into problems installing?](https://docs.mapbox.com/help/troubleshooting/ios-sdk-installation/)**
> 
> Read more about common installation issues in our troubleshooting guide.

## Part 3: Request a route

Request your first route and simulate a navigation experience using our drop-in UI, `NavigationViewController`.

Insert the following code snippets into your `ViewController`.

```swift
import UIKit
import MapboxDirections
import MapboxCoreNavigation
import MapboxNavigation
import CoreLocation

class ViewController: UIViewController {
    private let routingProvider = MapboxRoutingProvider()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Define two waypoints to travel between
        let origin = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.9131752, longitude: -77.0324047), name: "Mapbox")
        let destination = Waypoint(coordinate: CLLocationCoordinate2D(latitude: 38.8977, longitude: -77.0365), name: "White House")

        // Set options
        let routeOptions = NavigationRouteOptions(waypoints: [origin, destination])

        // Request a route using MapboxRoutingProvider
        routingProvider.calculateRoutes(options: routeOptions) { [weak self] result in
            switch result {
            case .failure(let error):
                print(error.localizedDescription)
            case .success(let response):
                guard let self = self else { return }
                // Pass the first generated route to the the NavigationViewController
                let viewController = NavigationViewController(for: response)
                viewController.modalPresentationStyle = .fullScreen
                self.present(viewController, animated: true, completion: nil)
            }
        }
    }
}
```

Run the application and you will see a simulated navigation experience along a route.

![A screenshot of the resulting application.](https://docs.mapbox.com/ios/assets/ideal-img/navigation-examples-basic.902086b.480.png)