A powerful, safe, and intelligent macOS command-line tool for writing ISO images to USB drives
- What's New
- Overview
- Installation
- How to Run
- Usage
- Safety Features
- Architecture
- Technical Details
- Use Cases
- Troubleshooting
- Contributing
- Roadmap
Spooky Features & Fixes!
- Halloween Theme: Spooky UI with Halloween emojis and themed messages
- Better CLI Interface: Ghostly banners and cursed confirmations
- Installation Fix: Fixed Makefile to install actual binary (not wrapper script)
- All v1.1.5 Features: Still includes fast writes (35-50+ MB/s), progress bars, and fake USB detection, just a patch
- Faster Interactions: Optimized Delay, allows faster start,list and etc.
Performance Revolution!
- FAST Writes: Direct I/O implementation achieves 35-50+ MB/s
- Real Progress Bar: Live speed, ETA, and percentage updates
- Fake USB Detection: Warns about counterfeit drives (Rufus-inspired)
- SHA-512 Support: Enhanced hash verification options
- Better UX: Drag-and-drop paths, simple y/n confirmations
- 16MB Buffers: Optimized for maximum throughput
See CHANGELOG.md for full details.
FlexingUSB is a native Swift command-line utility designed to make ISO-to-USB creation simple, safe, and transparent for macOS users. It's a modern alternative to tools like dd, asr, and Etcher—entirely terminal-based with professional-grade safety features and blazing-fast direct I/O writes.
- macOS: 10.15 (Catalina) or later
- Architecture: Intel or Apple Silicon (M1/M2/M3)
- Privileges: Administrator access for disk operations
- Storage: ~2MB for binary
- USB: Any external USB drive (will be erased during writing)
macOS versions: Supported on Catalina (10.15) and newer.
Requirements: Admin/sudo, external USB drive, and that you’re OK with the tool unmounting/erasing the target disk.
Performance: Similar or better on Intel—actual speed depends on your USB port (USB 2.0 vs 3.x), the drive, and the ISO size.
- FAST: Direct I/O writes at 30-50 MB/s (was 5-15 MB/s with dd)
- Real-time Progress: Live speed, ETA, and completion percentage
- Safety First: Never touches internal drives (
/dev/disk0) - multiple safety checks prevent accidents - Fake USB Detection: Warns about counterfeit drives with suspicious capacities (Rufus-inspired)
- Intelligent Detection: Automatically detects ISO types (Windows, Linux, macOS)
- Multi-hash Verification: SHA-256 and SHA-512 checksum support
- User-Friendly: Colorized terminal output with clean progress bars
- 16MB Buffers: Optimized for maximum throughput
- Drag-and-Drop: Easy file path input support
- USB Restoration: Easy restoration of USB drives to FAT32/exFAT
Clone the repository and use the Makefile to build and install FlexingUSB. Install Git on your machine (Recommend with brew)
# Clone the repository
git clone https://github.com/Goenvim/FlexingUSB.git
cd FlexingUSB
# Build and install
make installThis will build the release version of FlexingUSB, and install it to /usr/local/bin. You can then run FlexingUSB or flexingusb from anywhere in your system.
To uninstall FlexingUSB, run the following command from the project directory:
make uninstallAfter installation, you can run FlexingUSB from anywhere in your terminal
FlexingUSB requires administrator privileges to write to USB drives. Always run with sudo:
sudo FlexingUSB startYou can also run the compiled binary directly from the project folder:
# From the project's root directory
./.build/release/FlexingUSB startIf you already have a local clone or previously installed FlexingUSB, here are safe commands to update (reinstall) or remove the installed binaries. This section is intended to be non-destructive for your repo — inspect the commands before running.
Reinstall / update from a local clone:
cd /path/to/FlexingUSB
git pull --rebase origin main
make install # builds release and installs to /usr/local/binIf you installed via a release package (zip/installer), re-download the release and
re-run the bundled install.sh from the unpacked release directory.
Uninstall / delete installed commands:
sudo rm -f /usr/local/bin/FlexingUSB
sudo rm -f /usr/local/bin/flexingusbNotes:
- Always inspect
install.shand theMakefilebefore running them so you know what will be installed/overwritten. - If you installed manually (copied the binary into PATH), remove the binary from
wherever you placed it (for example
/usr/local/bin).
# Interactive ISO-to-USB workflow
FlexingUSB start
# List all external drives
FlexingUSB list
# Restore a USB to FAT32/exFAT
FlexingUSB restore
# Verify a written ISO
FlexingUSB verify /path/to/image.iso disk2
# Show technical specifications
FlexingUSB specs --iso /path/to/image.iso
FlexingUSB specs --usb disk2
# Quick operations
FlexingUSB quick flash --iso /path/to/image.iso
FlexingUSB quick restore
FlexingUSB quick infoThe main command that guides you through the entire process:
FlexingUSB start [--dry-run] [--skip-verify]Workflow:
- Detects all external USB drives
- Optional bad blocks/fake capacity check (Rufus-inspired)
- Prompts for ISO file path (drag-and-drop supported)
- Detects ISO type (Windows/Linux/macOS)
- Optionally provides Windows TPM bypass information
- Simple y/n confirmation before writing
- Writes ISO to USB with real-time progress (30-50 MB/s)
- Optionally verifies written data with SHA-256/SHA-512
Options:
--dry-run: Simulate the operation without actually writing--skip-verify: Skip the verification step after writing
Lists all connected external USB drives with detailed information:
FlexingUSB listOutput:
═══ External Drives ═══
Detected external drives:
[1] /dev/disk2 - 64.00GB SanDisk Ultra Fair (GUID_partition_scheme)
Device: /dev/disk2
Size: 64.00 GB
Content: GUID_partition_scheme
Volume: SanDisk
Mounted: /Volumes/SanDisk
Erases and formats a USB drive back to a usable state:
FlexingUSB restore [--format FAT32|ExFAT] [--name VolumeName]Options:
--format: Specify format (FAT32 or ExFAT). Auto-detects based on size if not specified--name: Custom volume name (default: "Untitled")
Example:
FlexingUSB restore --format ExFAT --name "MyUSB"Verifies that a USB drive matches an ISO file:
FlexingUSB verify <iso-path> <disk-identifier>Arguments:
iso-path: Path to the ISO filedisk-identifier: Disk identifier (e.g., disk2)
Example:
FlexingUSB verify ~/Downloads/ubuntu.iso disk2Shows detailed technical specifications for ISO files and USB drives:
FlexingUSB specs --iso <iso-path>
FlexingUSB specs --usb <disk-identifier>
FlexingUSB specs --allOptions:
--iso: Analyze an ISO file and show its technical specifications--usb: Analyze a USB drive and show its technical specifications--all: Show specifications for all available USB drives
Examples:
# Analyze an ISO file
FlexingUSB specs --iso ~/Downloads/ubuntu-22.04.iso
# Analyze a USB drive
FlexingUSB specs --usb disk2
# Show all available specifications
FlexingUSB specs --allFast shortcuts for common ISO-to-USB tasks:
FlexingUSB quick <operation> [options]Operations:
flash: Quickly flash an ISO to the first available USB driverestore: Quickly restore the first available USB drive to FAT32/exFATinfo: Show quick information about connected USB drivesstatus: Show system status and drive information
Examples:
# Quick flash (uses first available USB drive)
FlexingUSB quick flash --iso ~/Downloads/ubuntu.iso
# Quick restore (formats first available USB drive)
FlexingUSB quick restore
# Quick info about USB drives
FlexingUSB quick info
# System status
FlexingUSB quick status --iso ~/Downloads/ubuntu.isoFlexingUSB includes multiple layers of protection:
-
Internal Disk Protection:
- Automatically blocks operations on
/dev/disk0(internal macOS disk) - Verifies disk is external before any operation
- Automatically blocks operations on
-
Explicit Confirmation:
- Simple y/n confirmation before destructive operations
- Shows detailed information about what will be erased
-
Dry Run Mode:
- Test operations without actually writing data
- See exactly what commands would be executed
-
Verification:
- Optional SHA-256 and SHA-512 checksum verification
- Byte-for-byte comparison ensures written data matches source ISO
- Real-time hashing with progress indicators
-
Error Handling:
- Graceful error messages
- Safe cleanup on failures
FlexingUSB is built with a modular, maintainable architecture:
FlexingUSB/
├── Package.swift # Swift Package Manager configuration
├── Makefile # Build automation
├── Sources/FlexingUSB/
│ ├── main.swift # CLI entry point & command routing
│ ├── DiskManager.swift # Disk detection & operations
│ ├── ISOManager.swift # ISO detection & validation
│ ├── Writer.swift # ISO writing & verification orchestration
│ ├── DirectWriter.swift # Direct I/O writer (Rufus-style)
│ ├── BadBlockChecker.swift # Fake USB detection
│ └── UI.swift # Terminal UI & user interaction
└── Documentation/
├── README.md
├── INSTALL.md
├── QUICKSTART.md
├── CONTRIBUTING.md
├── SECURITY.md
└── VERIFICATION_REPORT.md
main.swift: ArgumentParser commands and workflow orchestrationDiskManager.swift: Disk enumeration, safety checks, formattingISOManager.swift: ISO type detection, file validation, checksum calculationWriter.swift: High-level write orchestration and verificationDirectWriter.swift: Low-level direct I/O writes with 16MB buffersBadBlockChecker.swift: USB capacity verification and fake drive detectionUI.swift: Terminal output, colors, progress bars, user prompts
- macOS: 10.15 (Catalina) or later
- Swift: 5.9+
- Xcode: 15.0+ (for development)
- Privileges: sudo access for disk operations
- Swift Package Manager: Dependency management and building
- ArgumentParser: Command-line argument parsing from Apple
- CryptoKit: SHA-256 and SHA-512 checksum calculation
- Foundation: Low-level file I/O, process execution, and POSIX APIs
- Darwin: Direct system calls for O_SYNC, fsync, and raw device access
FlexingUSB uses a high-performance direct I/O writer:
-
Direct I/O (default in v1.1.0+): Fast, native Swift implementation
- 16MB buffer size for maximum throughput
- Direct file-to-device writes (no external commands)
- Real-time progress with speed and ETA
- 30-50 MB/s average speed (3-5x faster than dd)
- Inspired by Rufus's approach
-
Legacy dd/asr (fallback): Available in Writer.swift for compatibility
- Uses external
ddcommand with raw disk device - Slower but universally compatible
- Uses external
Note: Actual speeds depend on:
- USB Port: USB 3.0/3.1 (5-10 Gbps) vs USB 2.0 (480 Mbps)
- Drive Quality: High-quality drives achieve 40-50 MB/s, budget drives 20-30 MB/s
- ISO Size: Larger ISOs benefit more from the optimized buffer size
- System Load: Background processes may impact performance
# Download Ubuntu ISO
# Run FlexingUSB
FlexingUSB start
# Follow interactive prompts
# Boot from USB on target machine# Download Windows 11 ISO
FlexingUSB start
# Tool detects Windows and offers TPM bypass info
# Creates bootable Windows USB# Download macOS installer DMG/ISO
FlexingUSB start
# Creates bootable macOS installer# Restore USB to normal storage
FlexingUSB restore
# USB is now formatted and ready for filesProblem: The flexingusb command doesn't work or you get a "binary not found" error.
Solution: This usually happens if the project hasn't been built correctly. To fix it, you can clean the build artifacts and then build the project again.
# Clean the build directory
make clean
# Build the release version
make releaseAfter this, the flexingusb command should work. If you want to install it system-wide, run make install.
Problem: FlexingUSB doesn't see your USB drive.
Solutions:
- Ensure USB drive is properly connected
- Try a different USB port
- Check Disk Utility to see if macOS recognizes the drive
- Try unplugging and replugging the drive
Problem: Insufficient privileges for disk operations.
Solutions:
- FlexingUSB requires admin privileges for disk operations
- You'll be prompted for your password when needed
- Ensure your user account has admin privileges
- Run commands normally (don't prefix with sudo)
Problem: Writing takes longer than expected.
Solutions:
- With v1.1.0+, writes should be 30-50 MB/s (check version with
FlexingUSB --version) - Typical times: 2.8GB ISO in 1-2 minutes, 4-5GB ISO in 2-3 minutes
- Ensure you're using USB 3.0 ports for faster speeds
- Avoid USB hubs when possible
- Slow USB 2.0 drives may only achieve 10-15 MB/s (hardware limitation)
Problem: USB checksum doesn't match ISO.
Solutions:
- The write may have failed - try writing again
- Check USB drive for hardware issues
- Try a different USB drive
- Verify ISO file isn't corrupted (check download)
Problem: Trying to use /dev/disk0.
Solution: This is intentional! FlexingUSB blocks operations on internal disks for safety. Use an external USB drive only.
Contributions are welcome! Here's how you can help:
# Clone and setup
git clone https://github.com/Goenvim/FlexingUSB.git
cd FlexingUSB
# Build debug version
make build
# Run without installing
swift run FlexingUSB list
# Build release version
make release
# Run tests (when available)
make test
# Format code (requires swift-format)
make format- Add unit tests for disk parsing and safety checks
- Implement actual Windows ISO patching (TPM removal)
- Complete bad blocks checking implementation
- Create Homebrew formula for easy installation
- Add localization support
- Add write speed benchmarking and comparison tools
- Add SwiftUI front-end option
- Improve error handling and recovery
- Add disk cloning functionality
- Create preset profiles for popular ISOs
- Use Swift naming conventions
- Add doc comments for public APIs
- Keep functions focused and modular
- Include error handling for all operations
- Write descriptive commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 FlexingUSB Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Direct I/O techniques inspired by Rufus by Pete Batard
- Also inspired by Etcher and traditional Unix utilities (
dd,asr) - Built with Swift and modern macOS frameworks
- Thanks to the open-source community for feedback and contributions
- Special thanks to the Swift community for ArgumentParser and excellent tooling
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: See QUICKSTART.md and INSTALL.md
- Security: See SECURITY.md
- Unit test suite
- Complete bad blocks implementation
- Write speed benchmarking
- Performance profiling tools
- Bug fixes and stability improvements
- Enhanced Windows ISO Handling with TPM Bypass
- Preset profiles for popular ISOs
- Multi-USB writing (parallel writes)
- Disk cloning functionality
- Network ISO downloads
- Enhanced verification options
- Homebrew formula
- Advanced features and community requests
- Performance optimizations
- Platform expansion considerations
- Plugin API to allow community-contributed profiles for ISO types, flash validation, and file system formatting.
- Develop an automatic recovery system that attempts partial writes or retries with gradually adjusted parameters on errors.
- More!
-
Quick Explaining
-
Quantum-resistant encryption is a new kind of security that protects data from being cracked by future super-powerful quantum computers. Imagine it as a super-strong lock that even the smartest, fastest computers can't pick open.
-
Right now, many of our online protections, like for websites and emails, use locks (called encryption) that regular computers can't break easily. But quantum computers will be able to break these old locks quickly. So, quantum-resistant encryption uses new kinds of math puzzles that are way harder for even quantum computers to solve.
-
In simple terms: it’s about making your USB data future-proof by locking it with next-generation, quantum-proof security that's ready before those powerful quantum computers arrive. This keeps your data safe for years to come.
This is just a concept for adding this to FlexingUSB, but in few years this kind of encryption could be used by Government Agencies and Defense, Healthcare Organizations, Cloud and Security Service Providers and More!
-
Protects Data from Future Quantum Attacks: It uses advanced encryption designed to resist cracking by powerful quantum computers expected in the next 10-20 years. This means the ISO files—and anything sensitive on the USB—stay secure long-term.
-
Prevents Tampering and Unauthorized Access: Encrypting the ISO during the flashing process ensures that even if someone tries to copy or modify the USB files, they won’t be able to access or alter the data without the quantum-resistant encryption keys.
-
Ensures Data Integrity for Sensitive Uses: For critical uses like government, finance, or corporate environments, this encryption method guarantees that the bootable USB is authentic and hasn’t been tampered with, reducing risks of malware or corruption.
-
Future-Proofs Bootable Media Security: Many USBs are used to install operating systems or critical tools; adding quantum-resistant encryption means these tasks stay safe from emerging cryptographic threats that classical encryption can’t withstand.
-
While typical users may not need this level of protection now, it greatly benefits those who require the highest security assurance for long-term data confidentiality and integrity on USB boot media.
Built for the macOS community