DebugSwift: An In-App Debugging Toolkit for iOS Apps

What DebugSwift Solves for iOS Developers

Xcode's debugger is attached to a build. DebugSwift moves part of that work into the app itself, so the questions you ask while the app is running on a device or simulator get answered on the screen rather than in a separate window. The README describes it as a toolkit for troubleshooting and performance work in Swift-based applications, and the feature list is organised into network inspection, performance, app tools, interface tools and resources.

The audience is narrow and that is a strength. You need an iOS app on iOS 14.0 or later, built with Swift 6.0 and Xcode 16.0. If you maintain a UIKit or SwiftUI app and you regularly need to see what a request returned, why a controller was not released, or what is actually stored in UserDefaults on the device, the toolkit targets exactly that loop.

What it is not: a crash reporting backend, a remote logging service, or something you ship to users. The setup example is wrapped in #if DEBUG, which tells you the intended deployment surface.

How the Toolkit Hooks Into a Running App

The mechanism is an in-process overlay. You instantiate a DebugSwift object, call setup() during didFinishLaunchingWithOptions, and call show() to present the interface. From that point the toolkit's own inspectors are active: the README lists HTTP monitoring that captures requests and responses with filtering, a WebSocket inspector described as zero-config, automatic JSON formatting, and a response modifier that can mock or change a response body and status by URL or pattern.

Some features are sampling or observation loops rather than interception. Real-time CPU, memory and FPS metrics, memory leak detection for leaked ViewControllers and Views, and a thread checker that reports main thread violations with stack traces all read state the app already produces. Others are browsers over storage the app already owns: the file browser walks the sandbox and shared app group containers, and there are viewers for UserDefaults, Keychain, SQLite, Realm and, on iOS 17+, SwiftData.

A few entries are explicitly labelled. SwiftUI Render Tracking is marked Beta in the README, which is the honest signal that re-render detection is not as settled as the network inspector. The response modifier, with CSV import and export and rule generation from live traffic, is the most opinionated piece: it changes what your app sees, so a rule left enabled can make a bug look like a fix.

Installing DebugSwift via Swift Package Manager or CocoaPods

The README recommends Swift Package Manager. In Package.swift you declare the dependency by URL with a from: version constraint, which is the normal SemVer range for a Swift package.

dependencies: [
    .package(url: "https://github.com/DebugSwift/DebugSwift.git", from: "1.0.0")
]

In Xcode the equivalent path is File > Add Package Dependencies and then the repository URL. CocoaPods users get two options, a plain pod line for a source distribution and an :http variant pointing at the DebugSwift.xcframework.zip asset on the latest GitHub release, which the README presents as faster builds.

pod 'DebugSwift'
# or, for the XCFramework distribution:
pod 'DebugSwift', :http => 'https://github.com/DebugSwift/DebugSwift/releases/latest/download/DebugSwift.xcframework.zip'

The setup call goes in the app delegate inside a DEBUG conditional. The commented line shows how to opt out of a single module by passing it to setup(disable:), so you can keep leak detection off while leaving the rest on.

#if DEBUG
debugSwift.setup()
// debugSwift.setup(disable: [.leaksDetector])
debugSwift.show()
#endif

The README also documents a shake-to-toggle extension on UIWindow that overrides motionEnded and checks for .motionShake. If your app already handles motion events, that override is the first thing to reconcile. On Apple Silicon, the README states that arm64 simulator builds are native and that existing EXCLUDED_ARCHS[sdk=iphonesimulator*] exclusions for arm64 can be removed.

Running the Example App Through the Makefile

The repository ships a Makefile that builds, installs and launches the Example app on a booted simulator, with every value overridable. This is the fastest path to seeing the toolkit without wiring it into your own project. The default bundle identifier is com.maatheusgois.debugswift.Example and the default scheme and project point at Example/Example.xcodeproj.

make run
make booted
make path

make run builds, installs and launches in one step. make booted prints the UDID and name of the booted simulator, which is what you need if you want to pass SIM_ID explicitly. make path prints the resolved .app location, and the Makefile comments give the shape of that path as <DERIVED>/Build/Products/Debug-iphonesimulator/Example.app. If no simulator is booted, the SIM_ID default resolves to an empty string, so boot one first. The repository also contains an Example.xctestplan, so the example doubles as a test target.

Where DebugSwift Is the Wrong Tool

The DEBUG wrapping is not decoration. Everything the toolkit does happens inside your process and, for the response modifier and UserDefaults editor, changes that process's state. Shipping it enabled means a tester or a user could alter network responses or preferences. If your requirement is diagnosing a problem that only appears in a release build, this toolkit does not address it.

The second constraint is the toolchain floor. iOS 14.0, Swift 6.0 and Xcode 16.0 rule out projects that have not moved to the Swift 6 toolchain, and the SwiftData browser additionally requires iOS 17+. Teams maintaining an older deployment target cannot adopt it without a separate build configuration.

Third, the README does not document rollback behaviour for the response modifier, nor does it describe what happens to persisted rules across launches. If you plan to use mocking in a shared test build, that gap matters more than the feature list suggests. The README is also silent on thread-safety and on the overhead the inspectors add, so treat the performance widget as something to measure in your own app rather than assume.

DebugSwift Compared with DBDebugToolkit

DBDebugToolkit is the closest well-known point of comparison, and it appears in the search phrases people use around this project. Both are in-app debugging overlays for iOS, and both cover network logging and device inspection. The difference is scope and toolchain. DBDebugToolkit predates the Swift 6 and Xcode 16 requirement, which is the practical dividing line: if your project is already on the Swift 6 toolchain and you want the newer surface area, DebugSwift's response modifier with CSV rule import and export, the SwiftData browser on iOS 17+, and the SwiftUI render tracking beta are the parts DBDebugToolkit does not offer. If you are pinned to an older Xcode, DBDebugToolkit remains the option that will build.

For teams already inside the Composable Architecture, the DebugSwift overlay is orthogonal. It inspects the app from outside the reducer, so it will not show you state transitions the way TCA's own debugging tools do. That is a complement, not a substitute.

Maintenance, Licensing and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-21. The three most recent releases, rc-1.20.4, rc-1.20.3 and rc-1.20.2, were all published on the same day, and they are release candidates rather than final tags. That pattern suggests you should pin an exact version in your dependency declaration instead of tracking a range, and read the release notes before moving a shared team build onto a new candidate.

The project is MIT licensed, which permits commercial and closed-source use and requires preserving the copyright notice and licence text. That is a description of the terms, not legal advice; your own counsel should confirm how it interacts with your distribution process.

Upgrade cost comes mostly from the DEBUG setup call and the UIWindow shake override, both of which live in your app delegate and window extension rather than in the package. A major version bump that changes setup() or the disable: option list will surface there. The Makefile and the Example app give you a way to check a new version against a working build before touching your own project.

Editorial conclusion

Adopt DebugSwift if your team debugs a running iOS app and wants network logs, leak detection and sandbox browsing without leaving the device. Skip it if you need something in a release build, since the README wraps setup and show in #if DEBUG and the toolkit is built around the simulator and a debug configuration. Verify first that your toolchain meets iOS 14.0, Swift 6.0 and Xcode 16.0, and check the release feed rather than the README for the version you pin, because the latest releases are published as rc-1.20.4, rc-1.20.3 and rc-1.20.2.

Frequently asked questions

Official sources

1. DebugSwift/DebugSwift on GitHub
2. License: MIT
3. Project website
4. README
5. Releases