Upload dSYMs

Upload dSYM files to allow BugSnag to show human-friendly function names, file paths, and line numbers in your iOS, macOS, and tvOS stacktraces.

For installation instructions for the BugSnag CLI, please see our Installation guide.


The dsym command uploads dSYM files from your build and uploads them to the dSYM upload API. The command will attempt to locate your dSYMs if provided with an Xcode project or directory, or else a direct path can be provided.

In addition to the source maps, the command extracts version and build information, including your BugSnag API key, required for the upload from your app’s Info.plist file. These values can be overridden, or provided entirely, by command line options.

Example usage

The simplest way to run the command is from the root directory of your project:

$ bugsnag-cli upload dysm

Or by providing a specific project file

$ bugsnag-cli upload dsym path/to/my-project.xcodeproj

Or to the dSYM itself:

$ bugsnag-cli upload dsym path/to/generated/project.dSYM

If your project contains multiple schemes or has a non-standard project layout, you might need to provide extra options:

$ bugsnag-cli upload dsym \
    --plist path/to/Info.plist \
    --scheme Production

Available options

API key (--api-key)

Your project’s API key. This defaults to the value of com.bugsnag.android.API_KEY in your app’s manifest file, if found.

You can find your API key in Project Settings from your BugSnag dashboard.

Dry run (--dry-run)

Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.

Ignore empty dSYM (--ignore-empty-dsym)

Throw warnings instead of errors when a dSYM file is found rather than the expected dSYM directory. Defaults to false.

Ignore missing DWARF (--ignore-missing-dwarf)

Throw warnings instead of errors when a dSYM with missing DWARF data is found. Defaults to false.

Log Level (--log-level)

Used to set the level of the logging. The available levels are debug, info, warn, and fatal. The default level is info.

Plist (--plist)

The path to the app’s Info.plist, which is used to extract app information required for the upload. By default, the command uses the build settings in your app’s project to locate the file.

Project root (--project-root)

Path to strip from the beginning of source file names referenced in stacktraces when displayed as an error in your dashboard. This will default to your project’s root directory if the command has detected one, otherwise it’s empty.

Retries (--retries)

The number of retry attempts before failing an upload. By default it is only attempted once.

Scheme (--scheme)

The Xcode scheme used to build the app.

Timeout (--timeout)

The number of seconds to wait before failing an upload attempt. By default the upload is given 300s (5 mins).

Upload API root URL (--upload-api-root-url)

The BugSnag On-premise upload server hostname, optionally containing port number. The command will append the appropriate path to access the correct BugSnag API upload endpoint.

Verbose (--verbose)

Used to set the level of the logging to its highest. This is the equivalent of setting log-level to debug.

Xcode Project (--xcode-project)

The path to your Xcode project, workspace or containing directory, from which the command attempts to automatically derive build locations and information for upload.