IsoZap

Create bootable USB drives safely from your terminal.

IsoZap is a cross-platform command-line utility for creating bootable USB drives from ISO images on Windows, macOS, and Linux.

WARNING: IsoZap writes directly to storage devices. Selecting the wrong disk may permanently destroy data. IsoZap includes safeguards designed to prevent accidental system-disk selection, but users remain responsible for confirming the correct destination device.

Overview

IsoZap discovers conservative removable/external whole-disk targets, validates the source and capacity, displays a destructive-operation summary, and requires explicit confirmation before writing. It supports raw hybrid images and specially prepared FAT32 Windows installer media.

Features

• Native device discovery for Windows, macOS, and Linux
• System-, boot-, internal-, and partition-target rejection
• Device identity and capacity revalidation immediately before writing
• Exact ERASE confirmation or an intentionally verbose automation flag
• Non-destructive --dry-run
• Source SHA-256 checking and optional raw-write read-back verification
• Windows x64 and ARM64 UEFI loader validation
• FAT32-compatible splitting of Windows install.wim files larger than 4 GiB
• Standard-library-only runtime

Supported operating systems

Python 3.9 or newer is required. ChromeOS, Android, iOS, and restricted Python environments generally do not expose raw USB disks and are not supported.

Supported ISO types and limitations

• Linux/Unix hybrid ISOs and raw .img files are written byte-for-byte.
• Arbitrary non-hybrid ISOs are not made bootable merely by writing them.
• Windows installer mode creates MBR + FAT32 media and validates the selected x64 or ARM64 UEFI loader.
• Windows installer mode does not guarantee legacy BIOS/CSM booting or support every customized ISO.
• Windows host support and creating media from a Windows ISO are separate capabilities.
• Platform logic and package builds are tested with mocks; release 0.1.0 has not yet completed broad physical-device testing.

Installation

Recommended:

pipx install isozap

Alternative:

python -m pip install isozap

Do not install IsoZap with sudo pip or an Administrator-level pip. Install as your normal user; elevate only the later flashing command when required.

Usage

isozap --help
isozap --version
python -m isozap --help

The existing direct command style is retained:

isozap IMAGE --type {hybrid,raw,windows}

Device listing

isozap --list

Only whole disks considered removable or external and not identified as system/boot disks are displayed.

Flashing an ISO

macOS or Linux:

sudo "$(command -v isozap)" ~/Downloads/ubuntu.iso --type hybrid
sudo "$(command -v isozap)" ~/Downloads/windows.iso --type windows --arch x64

Windows Administrator PowerShell:

isozap C:\Users\me\Downloads\ubuntu.iso --type hybrid
isozap C:\Users\me\Downloads\windows.iso --type windows --arch x64

Verify a publisher-provided source checksum and read back a raw write:

sudo "$(command -v isozap)" image.iso --type hybrid --sha256 EXPECTED_SHA256 --verify-write

For automation, --device still requires a currently safe discovered disk and --yes-i-really-mean-it explicitly replaces the prompt:

sudo "$(command -v isozap)" image.img --type raw --device /dev/sdX --yes-i-really-mean-it

Never guess a device identifier.

Dry-run

isozap image.iso --type hybrid --device /dev/sdX --dry-run

Dry-run performs source, target, identity, and capacity checks and displays the intended operation. It does not mount, unmount, repartition, format, write, or eject any device. Windows installer structural mounting is deferred until an actual operation.

Safety protections

IsoZap rejects partitions, internal/non-removable targets, known system or boot disks, insufficient capacity, targets that disappear, and targets whose size/name/hardware identity changes between selection and execution. Windows explicitly maps the running system drive; macOS protects startup and reported APFS physical stores; Linux follows the block-device tree containing /, /boot, or /boot/efi.

No automated safeguard can replace checking the displayed identifier, model, and size.

Administrator/root requirements

Listing and dry-run do not require application installation as an administrator. Actual raw-device access does. Windows users should open an Administrator terminal. macOS/Linux users should install normally, then use sudo only when launching the destructive flash operation.

Windows notes

IsoZap uses structured Get-Disk/Get-Partition PowerShell data and \\.\PhysicalDriveN; drive letters are never treated as physical disks. Raw writes take the selected disk offline during access and restore it afterward. Windows installer mode uses diskpart because repartitioning is necessary for MBR + FAT32 media. Windows' built-in formatter limits FAT32 to 32 GiB, so larger USB drives receive a 32 GiB installer partition and leave the remaining space unallocated.

macOS notes

IsoZap uses plist output from diskutil, rejects internal disks and the startup disk/known APFS backing stores, unmounts the selected whole disk, and writes through /dev/rdiskN for raw-image performance.

Linux notes

IsoZap uses JSON lsblk data and protects the top-level disk containing /, /boot, or /boot/efi, including nested LVM/device-mapper layouts represented in the block tree. Windows media additionally needs parted, dosfstools, and mount tools.

Development

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Testing

python -m pytest
isozap --help
isozap --version
python -m isozap --help

Tests mock destructive and system-level operations. Never point a test at a real disk.

Building

python -m build
python -m twine check dist/*

Contributing

See CONTRIBUTING.md. Platform changes require mocked safety tests.

Security

See SECURITY.md for private reporting guidance and security scope.

License

IsoZap is available under the MIT License. See LICENSE.

Disclaimer

IsoZap is provided without warranty. Successful writing does not guarantee that an image supports USB booting or that the target firmware supports the image. Back up important data and test only with a disposable USB drive until you are confident in your platform and image combination.