Metadata-Version: 2.4
Name: isozap
Version: 0.1.0
Summary: A safe cross-platform command-line utility for creating bootable USB drives from ISO images.
Author: Shariar Imtiaz
License-Expression: MIT
Project-URL: Homepage, https://github.com/simtiaz019/IsoZap
Project-URL: Issues, https://github.com/simtiaz019/IsoZap/issues
Keywords: iso,usb,bootable-usb,usb-flasher,iso-flasher,windows,macos,linux,cli,bootable,disk,flash
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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

| Host | Raw/hybrid images | Prepared Windows installer media |
|---|---:|---:|
| Windows | Yes | Yes, UEFI-focused |
| macOS | Yes | Yes, UEFI-focused |
| Linux | Yes | Yes, UEFI-focused |

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:

```bash
pipx install isozap
```

Alternative:

```bash
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

```text
isozap --help
isozap --version
python -m isozap --help
```

The existing direct command style is retained:

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

## Device listing

```bash
isozap --list
```

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

## Flashing an ISO

macOS or Linux:

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

Windows Administrator PowerShell:

```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:

```bash
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:

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

Never guess a device identifier.

## Dry-run

```bash
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:

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

Windows PowerShell:

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

## Testing

```bash
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

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Platform changes require mocked safety tests.

## Security

See [SECURITY.md](SECURITY.md) for private reporting guidance and security scope.

## License

IsoZap is available under the MIT License. See [LICENSE](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.
