swiftflash is a macOS command-line tool for flashing .img and .iso images to SD cards and USB sticks.
Images can be local files, .xz compressed, or loaded from an http(s) URL or a registered build server.
It is implemented 100% in Swift and uses only system frameworks:
Foundation, DiskArbitration, IOKit, Darwin / POSIX I/O, CryptoKit and Compression.
No external tools such as diskutil, dd, xz or curl are used for scanning, mounting, downloading,
unpacking or writing.
brew install zehrer/tap/swiftflash
swiftflash --versionThe Homebrew build runs on Apple Silicon Macs with macOS 13 or later. See Build to build it yourself.
SwiftFlash is a single native binary without bundled runtimes or dependencies (measured for 0.2.0):
| Size | |
|---|---|
Download (.tar.gz) |
390 KB |
Installed (/opt/homebrew/Cellar/swiftflash) |
1.2 MB |
| Memory, typical command | ~3 MB (peak footprint) |
| Memory, browsing a build server | ~13 MB (peak footprint) |
Flashing and verifying use fixed 4 MiB buffers, so memory use does not grow with the image size. Unpacking
.xz additionally needs the archive's dictionary (up to 64 MiB for xz -9). For comparison, GUI flashing tools
that bundle a browser runtime (Electron) usually need well over 100 MB of disk space.
swiftflash media list # connected SD cards / USB sticks
swiftflash id # which image is on the card (read-only)
sudo swiftflash ~/Downloads/image.img.xz /dev/disk6 # flash a local (compressed) image
sudo swiftflash https://example.com/images/os.img.xz # flash a remote image
sudo swiftflash # choose image and device interactivelyFlashing and verifying need sudo. Only external physical whole disks are offered as targets, and unless
--yes is given, SwiftFlash shows what is currently on the medium and asks before erasing it.
- Flash
.img/.iso, also.xzcompressed, from a local path or anhttp(s)URL - Image sources: register a build server directory once, then flash the newest build with
redox:<family> - Built-in Raspberry Pi image list (the one the Raspberry Pi Imager uses):
sudo swiftflash rpi:lite-64, filtered by board - Downloads are checked against a published
<image>.sha256and kept in the Trash for reuse - Optional verification of the written medium against the image (
-v, default configurable) swiftflash idshows which image is on a card before downloading or writing anything- Device selection and erase confirmation show the known name, media type and the image currently on the medium
- Identification of media and flashed images via a small
/.uuidfile (format), with a raw trailer copy at the end of the device when there is room - Remembered images, media inventory with names and media types, and flash history
- The medium is unmounted after flashing, so it can be removed right away
- Interactive shell when started without arguments
- Reusable
SwiftFlashCorelibrary target for a future GUI (the earlier SwiftUI app is archived as SwiftFlash-GUI)
sudo swiftflash [image] [/dev/diskX]
sudo swiftflash flash [image] [/dev/diskX] [-v|--no-verify] [--yes]
sudo swiftflash verify [image] [/dev/diskX]-v/--verifyreads the medium back after writing and compares it with the image;--no-verifyskips that. Neither option asks a question. Without them, a directswiftflash …does not verify (configurable, see Settings).--yesskips the erase confirmation.
image can be a local path, an http(s) URL, or <source>:<family> (see Image sources).
Without arguments, swiftflash starts an interactive shell; type commands like flash, media list or
history, and leave it with exit or quit.
All commands (swiftflash help shows the same list):
swiftflash images # remembered images
swiftflash images remove <name-or-path>
swiftflash images clear
swiftflash source add <name> <url> # image sources (build server directories)
swiftflash source list
swiftflash source browse <name> [family]
swiftflash source remove <name>
swiftflash media list # connected eligible media
swiftflash id [/dev/diskX] # what is on the medium (also: media id)
swiftflash media known # remembered media
swiftflash media info <name-or-device-uuid>
swiftflash media identify # create a device-uuid on new writable media (writes!)
swiftflash media types
swiftflash media type-add <type-name>
swiftflash media set-type <device-uuid> <type-name>
swiftflash media clear-type <device-uuid>
swiftflash media name <device-uuid> <name>
swiftflash media clear-name <device-uuid>
swiftflash history
swiftflash history clear
swiftflash versionLegacy swiftflash devices … commands are still accepted as aliases.
swiftflash id # all connected media
swiftflash id /dev/disk6 # one mediumShows, without downloading or writing anything, the remembered name and media type, the image on the medium
(name, version, build, file, source, SHA-256, flash date and flash UUID from /.uuid), and the earlier flashes of
this medium recorded on this Mac. The history is keyed by the medium's device-uuid, so it is only found when the
medium itself can be read.
- No
sudoneeded for/.uuidon a FAT partition. Usesudo swiftflash idfor media that only carry the trailer copy. - Without an
imageblock in/.uuid, api-genissue.txtis used, so Raspberry Pi OS cards show e.g.Raspberry Pi OS Lite 2026-10-06. - A medium that is not mounted (for example right after flashing) is mounted for reading and unmounted again.
swiftflash identifyis different: it writes a newdevice-uuidto unidentified media.
sudo swiftflash /path/to/sdcard.img.xz /dev/diskX
sudo swiftflash https://example.com/images/sdcard.img.xz /dev/diskX.xzimages are unpacked into a temporary directory; the original.xzfile is kept. The temporary directory needs enough free space for the unpacked image.- Remote images are downloaded into a temporary directory. After flashing or verifying (also when it fails),
the downloaded file is moved to the Trash of the user who ran
sudo, and the unpacked image is deleted. - The next time the same URL is used, SwiftFlash asks the server whether the file is unchanged (
ETag, orLast-Modifiedplus size) and takes the copy from the Trash instead of downloading again. If the server is not reachable, the copy from the Trash is used. An emptied Trash just means the image is downloaded again. - If a
<image>.sha256file (sha256sumformat) lies next to the image, the download is checked against it and SwiftFlash stops on a mismatch. A copy from the Trash is checked too and downloaded again if it does not match; offline, it is checked against the SHA-256 recorded at download time. Local files are checked the same way. - The remembered image list stores the original location (URL or
.xzpath), not the temporary file.
Register a build server directory once and use short names:
swiftflash source add redox http://homenodellm:8080/sdcard/
swiftflash source browse redox # families with their newest build
swiftflash source browse redox t18-direct # all builds of one family
sudo swiftflash redox:t18-direct # flash the newest build of that family
sudo swiftflash redox: # choose family and build interactively- The family can be given in full (
redox-rpi-t18-direct), as a suffix (t18-direct) or as a unique part (t18). An ambiguous short form is rejected with the list of matching families. - The interactive image selection also offers
redox) Browse …. - SwiftFlash reads
index.jsonif the server has one, otherwise the directory listing plusLast-Modified. - What a build server should provide is described in docs/build-server.md.
The source rpi is built in and reads the OS list of the Raspberry Pi Imager
(Raspberry Pi OS, Ubuntu, LibreELEC, Home Assistant, RetroPie, …):
swiftflash source browse rpi # all images by category, with the boards they run on
swiftflash source browse rpi --model pi4 # only images for a Raspberry Pi 4
sudo swiftflash rpi:lite-64 # Raspberry Pi OS Lite (64-bit)
sudo swiftflash rpi:ubuntu-server-24 --model pi5- Families are the image names in lower case, e.g.
raspberry-pi-os-lite-64-bit; short forms work as for other sources. - The board is set with
settings rpi-model pi5in the interactive shell (anyshows everything) or per command with--model. Models:pi5,pi4,pi3,pi2,pi1,zero2w,zero. - After unpacking, the image is checked against the SHA-256 published in the list.
- Images packed as
.zip,.gz,.bz2or.zstare not listed yet. - First-boot settings of the Imager (Wi-Fi, SSH, user) are not supported.
Settings are changed in the interactive shell (swiftflash without arguments) and stored in the config file.
Direct commands and the interactive shell have separate values:
swiftflash> settings
verify ask (flash in the interactive shell)
verify-console never (swiftflash … without -v / --no-verify)
swiftflash> settings verify always
swiftflash> settings verify-console ask
swiftflash> settings rpi-model pi5
For verify and verify-console the values are ask, always and never. -v and --no-verify always win;
with --yes, ask counts as never. rpi-model filters the Raspberry Pi images
(any for no filter); --model overrides it.
- Without an image, SwiftFlash lists remembered images and configured sources, and accepts a new path or URL.
- Without a device, it scans for external physical whole disks; a single eligible device is proposed directly.
- For each device it shows whether the medium is known (name, media type,
device-uuid) and what is on it (image version, file and flash date), or the volume names of an unknown medium. - Unless
--yesis used, the flash flow asks for a final confirmation and says what will be replaced. - After writing, it verifies the medium, asks, or skips it, as set with
settings verify(default: ask).
Configuration, inventory and history are stored in:
~/.swiftflash/config.json
Under sudo, the path is resolved against the invoking user, and the file is handed back to that user after
saving, so later commands without sudo can still update it.
The file contains:
mediaTypes— starts withUSB Stick,SD Card,Micro SD CardrememberedImagesknownPhysicalDevices— tool-managed device UUIDs plus user-meaningful metadata (no reader vendor/model labels)knownFlashMediaflashHistorytrashedDownloads— downloads kept in the Trash for reuseimageSourcessettings—verifyConsoleandverifyInteractive(ask,alwaysornever),rpiModel
The layout is intended to stay compatible with a future SwiftFlash GUI.
- Resolve
<source>:<family>, download remote images, check them against.sha256, and unpack.xzinto a temporary directory; validate the image file and size. - Scan only eligible external physical whole-disk devices and show what is on them.
- Read an existing
/.uuidfrom mounted partitions (or the trailer) to reuse thedevice-uuid. - Unmount the whole disk through Disk Arbitration.
- Write the image to the raw device node with POSIX I/O, showing progress and speed.
- Verify the raw device contents against the image if
-vor the settings ask for it. - Flush data with
fsyncandF_FULLFSYNC. - Remount the partitions.
- Write
/.uuidon a writable partition, keeping animageblock the image may ship in its own/.uuid. - If at least 1 MiB is free after the image, also write the metadata into the last 4 KiB of the device.
- Persist image usage, device inventory and flash history.
- Unmount the medium so it can be removed (also after
verify). - Move a fresh download to the Trash and delete the other temporary files.
Requires Xcode with Swift 6.2 or later.
xcrun swift build
xcrun swift test
./.build/debug/swiftflash help- Bump
Sources/SwiftFlashCore/Version.swift, update RELEASE.md, commit and push. - Build the archive and the formula:
The script checks the version and a clean working tree, runs the tests, builds an arm64 release binary, and writes
scripts/release.sh 0.3.0
dist/swiftflash-<version>-macos-arm64.tar.gzplusdist/swiftflash.rb(frompackaging/homebrew/swiftflash.rb.template). - Tag and publish (the script prints these commands):
git tag v0.3.0 && git push origin v0.3.0 gh release create v0.3.0 dist/swiftflash-0.3.0-macos-arm64.tar.gz --title v0.3.0 - Copy
dist/swiftflash.rbtoFormula/swiftflash.rbin zehrer/homebrew-tap and push it;brew upgradethen offers the new version.
Sources/
SwiftFlashCore/ models, persistence, device scanning, Disk Arbitration, image download/unpack/checksums,
image sources, UUID metadata, flash service
swiftflash/ CLI entry point, command execution, progress output
Tests/
SwiftFlashCoreTests/
docs/ file formats and guides
scripts/ release script
packaging/homebrew/ formula template
- docs/uuid-file.md — the
/.uuidmetadata file and how images can identify themselves - docs/build-server.md — what a build server should provide for SwiftFlash
- RELEASE.md — release contents and planned work
- macOS only; the Homebrew build is arm64 only.
- Flashing and verifying require root, typically via
sudo. .gzimages are not supported yet.- Tested mainly with SD cards in USB card readers; more hardware coverage is welcome.
MIT. See LICENSE.