SYM is a Mac crash symbolicator that finds your dSYMs before you ask

Open a crash report, and the symbols are found for you

SYM is described as a macOS app for symbolicating Apple crash reports. The README puts the workflow in one sentence: open a .crash or an .ips, let SYM find the matching dSYMs, and turn hex stacks into something you can actually read.

The feature list for users breaks that down. It opens Apple crash reports, classic .crash, IPS, and a few related JSON formats, and you can also paste a log straight into the editor. It looks for matching dSYMs on your Mac, including Xcode Archives, and you can import them by hand if needed. Symbolicating happens in one click, with Find and Undo working as you would expect, which is a detail that matters because symbolicating is a transformation you may want to reverse.

The order of operations in the How to use it section is the app's actual workflow. Grab the app from Releases and install it. Open a crash file, or paste the log into the editor. Check the toolbar or the dSYM sheet for matches, and if nothing shows up, import a dSYM or set up a download script and hit Download. Then click Symbolicate, and use the keyboard shortcuts for search and undo afterwards.

The requirement is macOS 13 or later, and the app is a native Swift application, with the primary language of the repository listed as Swift.

Where the dSYMs come from is the part that actually decides your workflow

The hard part of crash symbolicating is rarely the symbolication. It is finding the right dSYM for the exact build of the binary that crashed, and a dSYM is only useful if it matches the build UUID of the binary in the report.

SYM takes that problem on in two ways. Locally, it searches the machine for matching dSYMs, and the README explicitly says this includes Xcode Archives, which is where most teams keep the dSYMs for shipped builds. If it finds nothing, you can import a dSYM by hand.

For teams that keep dSYMs on a server rather than on the machine of whoever is reading the crash, there is an optional download script. The Settings panel holds the download folder and the download script, and the README describes the feature as an optional download script if your dSYMs live on a server.

That is a meaningful design choice. The alternative is that every person doing triage needs a working symbolication setup on their own Mac, with the right dSYMs downloaded and the right tool paths configured. SYM lets the team ship one script and the app calls it.

One thing to know before you rely on it: the matching is only as good as the symbols available. If the build that crashed is not in Xcode Archives and is not in the server the script points at, the tool has nothing to work with, and that failure looks like a matching problem rather than a missing artefact.

The dSYM panel in the toolbar is where you see which binaries have symbols, so that is the first place to look when nothing appears to match.

Pulling crashes off a connected iOS device

The Devices section is the part that goes beyond symbolicating.

The README says SYM talks to a connected iOS device, so you can pull crashes off the device and browse an app's sandbox. The Devices entry in the list of useful places in the UI is described as importing crashes from a phone and browsing sandboxes.

This matters for the workflow it enables. A crash that happened on a device and has not been uploaded anywhere is only useful if you can get it off the device and symbolicate it. Otherwise the path is to reproduce the crash on a developer's Mac, which is slower and often impossible if it depends on device state.

The repository layout shows the cost of that feature. There is an icp/ directory and a tools/ directory alongside the app, and the README documents an occasional maintenance task for rebuilding the vendored device libraries.

cd SYM/Device && ./build.sh

Vendored libraries with their own build script means a dependency you have to rebuild by hand when it changes, not a package manager pull. That is a maintenance cost you accept in exchange for not depending on a third party tool at runtime, and it is the kind of detail that tells you how the project is put together.

Settings that matter, including the hardware model list

The Settings panel is more than preferences, and the README enumerates what is in it: font, highlight color, line numbers, summary bar, download folder and script, and hardware model name updates.

Most of those are cosmetic. The hardware model name updates are not, and they are worth understanding.

Apple crash reports identify the hardware model by an internal identifier rather than a marketing name. SYM bundles a list that maps those identifiers to names a human recognises, and there is a script to refresh it.

./scripts/update-hardware-models.sh

Users can also trigger the same thing from the interface, through Check for Updates under Settings and Hardware Models. So the list is refreshed either by the maintainer, when a new model appears and the bundle is regenerated, or by the user, who pulls a newer list without waiting for a release.

The summary bar and highlight color are for reading long reports, which is the actual activity. A crash report is mostly boilerplate, and being able to highlight the interesting part and see a summary without scrolling is the difference between triaging a report in a minute and not looking at it.

The download folder and script settings sit alongside the cosmetic ones in the same list, which tells you how little the app differentiates between them: it is a small tool with a single workflow.

Building and testing it from the terminal

The developer section is written for contributors and the build is a plain Xcode project, SYM.xcodeproj, with Swift packages that resolve on first open or first build. The stated environment is macOS 13 or later and a recent Xcode with Command Line Tools.

The run and test commands are given for the terminal as well as for the Xcode scheme, which is the SYM scheme with a My Mac destination.

xcodebuild -scheme SYM -destination 'platform=macOS' build
xcodebuild test -scheme SYM -destination 'platform=macOS'

And there is a narrower target for the crash parsing tests alone, which is the part of the codebase where a regression is most likely to hurt.

xcodebuild test -scheme SYM -destination 'platform=macOS' -only-testing:SYMTests/CrashReportTests

That filter is a good signal about how the project is structured. The parsing of crash reports is separated into its own test target, SYMTests/CrashReportTests, and the README documents how to run just that subset. Crash format parsing is the fragile part of the whole tool, because Apple changes the format between OS versions, so isolating it is a sensible way to keep the test suite fast and the failures readable.

The repository top level shows the rest of the structure: SYM/ for the app, SYMTests/ for the tests, the Xcode project, a Makefile, scripts/, images/, icp/ and exportOptions.plist.

The Makefile is the release process, including notarization

SYM ships as a signed and notarized app, and the Makefile is the whole release flow. The README lists the targets directly.

# Archive a Release build and export the .app
make archive

# Same, but bake in a download script
make archive script=/path/to/download.sh

# Notarize (needs a notarytool keychain profile named "Notarization")
make notarize

# Build a DMG under dist/
make dmg

# Copy into /Applications
make install

Output lands in build/ and dist/, and make clean removes it. The version bump before a release is make next, which runs agvtool next-version, or you can edit Version and Build under Target SYM in the Xcode project. The marketing version and build number live in the Xcode project itself, the README giving 0.9.0 and 110 as an example.

The archive target has a conditional branch that is worth reading. If a script variable is set, the build passes BUILDIN_DOWNLOAD_SCRIPT_PATH into xcodebuild so the download script is compiled into the binary. That is how a team ships a preconfigured SYM to their own engineers, and it explains why the download script feature exists as a build time option rather than only as a runtime setting.

The notarize target is the part a hobby project often skips, and this one does not. It zips the app with ditto, submits it with xcrun notarytool submit using a keychain profile named Notarization, waits for the result, staples the ticket to the app, and then runs spctl to assess it. That is a complete chain from unsigned build to a Gatekeeper-clean app, and it is the difference between an app people can double click and one they have to right click and open anyway.

The Makefile itself reads the version straight out of the Xcode project file with sed, so the version and the build directory names cannot drift apart.

MIT licensed, still taking commits, but the last tag is old

The licence is MIT, with the text in the LICENSE file, and the README states it plainly in the License section.

The maintenance picture has a wrinkle in it. The repository is not archived and the last push was on 2026-08-28, so work is continuing. The README's own version example, 0.9.0 with build 110, is higher than the most recent tagged release, which is v0.8.8 from 2022-11-12, preceded by v0.8.7 in July 2022 and v0.8.6 in March 2022.

So the tree is ahead of the newest tag by a good margin, and the versioning scheme of marketing version plus build number in the Xcode project means the released binaries and the source can look quite different. The README points at the latest release page for the download, so the version you get is whatever the last tag carried, not whatever is on master.

That is a reasonable thing to know before you file an issue, because a behaviour you see in a build from 2022 may already have been changed.

The remaining detail is the hardware model list again, and it is the piece most likely to need attention. A list of internal identifiers to friendly names has to be updated whenever Apple ships a new Mac, and the script and the in-app check for updates are the two mechanisms for that. A user on a very new machine who sees a raw identifier in a report rather than a model name is looking at a stale bundle, not a broken app.

Editorial conclusion

Adopt SYM if you read Mac or iOS crash reports regularly and want a graphical tool that finds the right dSYMs for you instead of a command line ritual with atos and dwarfdump. Do not adopt it if you need a command line only pipeline for CI, or if you are on macOS 12 or older, because the app requires macOS 13 or later. Before you install, check that your dSYMs are actually on the machine or reachable by the download script, since the tool can only symbolicate with symbols it has, and note that the newest tagged release is v0.8.8 from 2022 while commits have continued since.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zqqf16/SYM on GitHub