Sparkle setup · SwiftUI
How to set up Sparkle in a modern Mac app
Give your Mac app a proper “Check for Updates” menu item and deliver signed updates from your own host. This guide walks through Sparkle 2 integration in a SwiftUI app, from the package to a real update test.
By Francisco Cantu ·
Before you start
Sparkle is an open-source update framework for macOS apps distributed outside the Mac App Store. It checks an XML feed called an appcast, downloads an update, verifies it, and installs it. It does not replace Apple code signing or notarization.
This example assumes you already have a SwiftUI macOS app in Xcode. You will need:
- A macOS deployment target supported by the Sparkle release you choose. Check its release notes before adding it.
- An HTTPS host for an appcast and release archives. A static web server or object storage such as Cloudflare R2 works.
- For public distribution, an Apple Developer account and a Developer ID Application certificate, plus a way to notarize your releases.
- Two builds with different build numbers to test an actual upgrade.
The examples use MyApp and updates.example.com. Replace these with your app name and your real update address.
1. Add the Sparkle package
In Xcode, choose File → Add Package Dependencies… and enter the official repository URL:
Swift Package Manager repository
https://github.com/sparkle-project/SparkleChoose a current stable Sparkle 2 release compatible with your deployment target, then add the Sparkle package product to your macOS application target. Do not choose a pre-release just because its version number is higher.
Build the app once. The package integration should make import Sparkle available and embed the framework in the app. If Xcode cannot find the module, check that you added the product to the app target, not only to a test target.
See the official Sparkle setup guide for framework integration details.
2. Create an update signing key
Sparkle uses an EdDSA key pair to verify update archives. This is a different key from your Apple Developer ID certificate: Apple signs your app; Sparkle signs the file users download to update it.
Locate the bin folder in the resolved Sparkle package’s binary artifact, or download the matching official Sparkle release that includes its tools. The package artifact is typically under Xcode’s DerivedData, inside SourcePackages/artifacts/sparkle/Sparkle. The exact path depends on your project and package version.
From that Sparkle tools folder, run:
Terminal · inside Sparkle’s bin folder
./generate_keysThe tool creates an update signing key pair, stores the private key in your macOS Keychain, and prints the public key. Copy the public key for the next step.
Keep the private key private—and keep it safe.
Never commit it, include it in your app, or upload it to your update host. Follow Sparkle’s instructions for a secure backup. Do not generate a fresh key for each release: existing installations must be able to verify your next update.
3. Configure your update feed
Add these entries to your app target’s Info settings or its Info.plist. Use the raw key names and String values:
Info.plist entries
<key>SUFeedURL</key>
<string>https://updates.example.com/myapp/appcast.xml</string>
<key>SUPublicEDKey</key>
<string>YOUR_PUBLIC_EDDSA_KEY</string>SUFeedURL points to the XML appcast, not directly to a ZIP file. SUPublicEDKey contains the public key printed by generate_keys. Neither value is secret; both ship inside the app.
If Xcode generates your Info.plist, add the entries to the target’s Info tab rather than creating an unreferenced plist file. Confirm both keys are present in the built app’s Info.plist.
For this guide, leave automatic-check settings at their defaults. Sparkle normally asks the user on the second launch whether to check automatically. SUEnableAutomaticChecks changes that initial default; it is not required for a manual Check for Updates menu item. Automatic checking and automatic installation are separate settings.
See Sparkle’s configuration reference before overriding those defaults.
4. Add the SwiftUI updater
Create one SPUStandardUpdaterController and retain it for the app’s lifetime. Its standard user interface handles update prompts and progress. Do not create an updater inside a view’s body, where it could be recreated as the view changes.
The example below adapts Sparkle’s official SwiftUI approach. Merge it into your existing app entry point—do not add a second @main app. Keep your own ContentView and any existing scenes or commands.
Swift · app entry point and updater
import SwiftUI
import Combine
import Sparkle
@MainActor
final class UpdaterModel: ObservableObject {
let controller: SPUStandardUpdaterController
@Published private(set) var canCheckForUpdates = false
init() {
controller = SPUStandardUpdaterController(
startingUpdater: true,
updaterDelegate: nil,
userDriverDelegate: nil
)
controller.updater.publisher(for: \.canCheckForUpdates)
.assign(to: &$canCheckForUpdates)
}
func checkForUpdates() {
controller.checkForUpdates(nil)
}
}
struct CheckForUpdatesCommand: View {
@ObservedObject var updater: UpdaterModel
var body: some View {
Button("Check for Updates…") {
updater.checkForUpdates()
}
.disabled(!updater.canCheckForUpdates)
}
}
@main
struct MyApp: App {
@StateObject private var updater = UpdaterModel()
var body: some Scene {
WindowGroup {
ContentView()
}
.commands {
CommandGroup(after: .appInfo) {
CheckForUpdatesCommand(updater: updater)
}
}
}
}@StateObject retains the model, which retains the controller. The Combine subscription observes Sparkle’s canCheckForUpdates property so the menu item is disabled while another check or update is in progress. The updater runs on the main actor.
Build and launch. Your app’s menu should now contain Check for Updates…, after the About item. Until the feed is published, a check may report a feed error—that does not mean the menu integration failed.
For an AppKit app, use the same controller from your app delegate and connect an NSMenuItem to its checkForUpdates(_:) action. Sparkle documents both approaches in programmatic setup.
5. Check sandbox settings
If your app is not sandboxed, you do not need Sparkle’s sandbox-specific setup. Distributing outside the App Store does not, by itself, mean an app is sandboxed.
If App Sandbox is enabled in Signing & Capabilities, follow the official sandboxing guide before testing installation. Sparkle uses XPC services to perform work outside your app’s sandbox.
The setup includes SUEnableInstallerLauncherService and the required mach-lookup entitlements. Downloader configuration also depends on whether your app already has outgoing network access. Copying just one plist key is not a complete sandbox integration; use the full instructions for your configuration.
Do not disable the sandbox or Hardened Runtime simply to silence an update error. They are separate security features, and Sparkle can be integrated without removing them.
6. Publish a signed update
The updater is only half the setup. It also needs a real appcast that describes a newer, downloadable release.
- Increase the build number. For a simple test, move
CFBundleVersionfrom1to2. The marketing version,CFBundleShortVersionString, is the user-facing version. Keep build numbers increasing across releases. - Archive and export the app. For a public release, sign it with Developer ID, notarize it with Apple, and staple the notarization ticket before making the final ZIP.
- Create the archive without breaking symlinks. Framework bundles contain symlinks. Use
dittorather than a ZIP method that loses them.
Terminal · package your final app
mkdir -p ./updates
ditto -c -k --sequesterRsrc --keepParent ./MyApp.app ./updates/MyApp-1.1.zipRun Sparkle’s generate_appcast tool against the folder containing the release archive. Replace the path to the tools folder with yours:
Terminal · generate and sign the appcast
/path/to/Sparkle/bin/generate_appcast --download-url-prefix https://updates.example.com/myapp/ ./updatesThe tool reads the archived app’s version information and generates the appcast, signing updates with the key available in your Keychain. Review the generated XML: the enclosure URL must match the final download address, and the archive must have a Sparkle EdDSA signature.
Upload the archive first, then the appcast, so you never advertise a file that is not available yet. Serve both over HTTPS. Make the appcast available at the exact SUFeedURL shipped in your app, without a login page or browser-only download flow.
Do not change or repackage the ZIP after signing it: the signature covers the archive’s exact bytes. Sparkle also provides sign_update for manually managed feeds, but generate_appcast avoids writing signatures and enclosure metadata by hand.
For release notes, additional options, and archive formats, see publishing an update.
7. Test the complete update
A successful launch in Xcode is not a complete update test. Test the path your users will take:
- Install an older, signed build in
/Applications. It must already contain Sparkle, your feed URL, and your public key. - Publish the newer signed build and its appcast. For the example above, the installed build is
1and the feed advertises build2. - Launch the installed app, not the copy running from Xcode. Choose Check for Updates….
- Confirm Sparkle offers the newer version, downloads it, verifies it, installs it, and relaunches the app.
- Check the installed version and build number. Then check again: it should report that you are up to date.
Keep your key and feed address stable between those builds. Verify that your host serves the current XML rather than a cached older appcast.
Common setup problems
“No such module Sparkle”
Check the package product’s target membership and make sure the app target links Sparkle. Resolve packages again if Xcode has not downloaded the artifact.
The appcast cannot be loaded
Open the exact feed URL and inspect the response. It must return appcast XML, not an HTML error page or a login screen. Check HTTPS certificates and redirects. Fix HTTPS rather than adding a broad App Transport Security exception.
Sparkle says the app is already up to date
Compare the installed build number with the appcast’s sparkle:version. Confirm the hosted feed is fresh, the advertised build is newer, and the release supports the Mac’s macOS version.
The update signature is invalid
Check that the old app’s SUPublicEDKey matches the private key used to sign the new archive. Also check that the uploaded archive is exactly the file you signed.
The download works, but installation fails
Check signing and notarization, archive symlink preservation, and—if applicable—the complete sandbox/XPC configuration. Read the app’s logs in Console for the underlying error.
Set it up once. Simplify every release.
Once Sparkle is integrated, every release still needs a build, Apple signing and notarization, a signed archive, and an updated appcast. HarborPilot handles that release workflow on your Mac and uploads the files to your own host, or gives them to you to upload. It can also help add Sparkle to an existing Xcode project with changes you can review.
Official references
This guide follows Sparkle 2’s documentation. Check the documentation for the version you use, especially when changing sandbox settings or adopting a newer release.
- Sparkle setup
- SwiftUI and AppKit integration
- Configuration keys
- Sandboxing
- Publishing updates
- App Transport Security
HarborPilot is not affiliated with the Sparkle project.