Greaseweazle Host Tools: Installation and Raw Floppy Use

Why Greaseweazle Works Below the Filesystem

Greaseweazle Host Tools solves a specific preservation and analysis problem: accessing a floppy drive at the raw flux level rather than beginning with a mounted filesystem or a finished disk image. The README describes the companion Greaseweazle as an open source USB device capable of reading and writing raw data on nearly any type of floppy disk. Its users include archivists recovering disks, retro-computing researchers investigating disk formats, and developers building software against historical media.

That boundary matters. A normal filesystem copy does not expose every transition encoded on the disk, while raw-flux access operates below that abstraction. The README does not specify supported capacities, encodings, drive types, or platform-specific disk behavior, so the project should not be presented as universally compatible. It also does not document a complete disk-imaging workflow. The GitHub wiki is the stated source for detailed usage instructions.

This repository contains the host-side software only. Firmware development lives in the separate `greaseweazle-firmware` repository. Users need both sides of the system to perform the hardware operations described by the project: the USB device and its firmware, plus this Python package and its `gw` command. Greaseweazle is consequently a poor fit for someone who only wants to read an already mounted USB drive or convert a conventional image. Its function concerns the recorded floppy signal handled through a purpose-built interface.

The Python CLI, Dependencies, and Compiled Components

The package configuration registers this console entry point:

'console_scripts': ['gw=greaseweazle.cli:main']

This line from `setup.py` shows that installation exposes a `gw` executable and routes it to `greaseweazle.cli:main`. The README directs users to `gw --help` for online command help. The documented interface is therefore a command-line tool rather than a graphical application described by the repository.

The package requires Python 3.8 or later and declares dependencies on `crcmod`, `bitarray>=3`, `pyserial`, and `requests`. Based on the repository layout, Greaseweazle combines Python host logic with a compiled extension named `greaseweazle.optimised.optimised`. Its declared C sources cover Apple GCR, Apple II, Commodore 64, Mac, and TD0 LZSS processing. These filenames show that the repository contains optimized code associated with several disk-processing paths. They do not, by themselves, establish the exact transformation performed by every module.

The build configuration uses `setuptools`, `setuptools_scm`, and `wheel`. Version information is derived from repository metadata through `setuptools_scm`, while the package includes `.cfg` files under `greaseweazle.data`. The visible architecture is a CLI-driven Python package with device-facing dependencies, packaged configuration data, and native code for selected processing paths. The README does not include the USB protocol trace or a command-level description of how flux samples cross the interface, so a more specific account of that data flow cannot be verified from this documentation.

Installing the Host Tools on Linux and macOS

For Linux and macOS, the README gives a direct Python Pipx installation of the latest release from GitHub as `@latest`:

pipx install git+https://github.com/keirf/greaseweazle@latest

This command asks Pipx to install Greaseweazle directly from GitHub. A successful installation should expose the `gw` entry point declared in `setup.py`. The README links to the software installation wiki for additional details, including platform prerequisites that are not stated in the repository excerpt.

Windows uses a different distribution model. The instructions say to download the latest host-tools release, unzip it, open a Command Prompt window inside the unzipped folder, and run `gw.exe`. The README does not prescribe a PowerShell command, installer, or registry configuration, so those steps should not be inferred.

The first documented action after installation is the help command:

gw --help

On Windows, users should invoke the executable named in the README, `gw.exe`, rather than copy the Unix-style `gw` command. The expected result is the tool's online help. The README does not document a first disk-read command, device enumeration output, or a sample capture session, so this tutorial stops at help discovery instead of inventing a flag. The GitHub wiki contains the detailed usage instructions needed for connecting a drive and selecting a read or write workflow.

Raw-Flux Capability Versus an Incomplete Workflow

The central capability is direct raw reading and writing, but the README does not explain the entire path from magnetic transitions to a named disk file. It gives no command for selecting a drive, choosing image encoding, setting a cylinder range, or handling write protection. It also does not say whether the host tool performs formatting, recovery retries, or platform-specific decoding automatically. Those omissions matter for a destructive operation such as writing a floppy.

There is also a hardware dependency that cannot be removed by installing Python packages alone. The repository refers to a Greaseweazle USB device and links to a separate firmware repository. The README does not describe firmware version negotiation, device discovery across multiple adapters, or recovery behavior after USB communication fails. A user therefore needs the hardware documentation as well as the host-tool wiki before relying on the software for archival work.

The phrase “nearly any type” in the README should be treated as a broad capability claim rather than a compatibility matrix. No list of verified drives or disk formats appears there. Likewise, the optimized source filenames mention several historic computer families, but they are not evidence that every image format or drive mechanism is supported. Engineers evaluating this package should distinguish between the device's stated raw-data role and the narrower set of commands and formats confirmed in documentation.

This makes Greaseweazle unsuitable for unattended adoption based only on its package description. The software reaches into media handling where an incorrect write can alter a physical disk. The README provides no confirmation prompts, dry-run behavior, maximum write counts, or rollback procedure. Users must consult the wiki and `gw --help` before selecting operating parameters.

Source Checkouts, Native Builds, and Package Lifecycle

For contributors or environments that install from a checkout, the Makefile exposes an `install` target that invokes Python's package installer:

install:
	$(PYTHON) -m pip install .

The variable `$(PYTHON)` is supplied through the included `Rules.mk`; the repository files do not show how it is selected. Because the target is written as `$(PYTHON) -m pip install .`, it should be invoked through `make install` rather than copied literally into a shell when `Rules.mk` or the environment has not defined `PYTHON`. The Makefile also offers `uninstall`, `clean`, `dist`, `windist`, `version`, and `mypy` targets.

The build declares a native extension, so a source installation may require a working compiler environment in addition to Python. The configuration does not document toolchain names or versions. Linux compilation adds `-Wall -Werror`; other platforms do not receive those extra compiler arguments. That setting can turn compiler warnings into build failures on Linux, which is a concrete source-installation limitation for developers using a toolchain that produces warnings.

The `clean` target removes build products, generated package metadata, optimized shared objects, caches, and directories matching `greaseweazle-*`. The Windows distribution target installs the package, prepares version and documentation files, and copies executable output built by `scripts/win`. These entries describe a conventional Python build with native and platform packaging paths. The README nevertheless directs standard macOS and Linux users to the Pipx installation instead.

Greaseweazle Licensing, Releases, and Upgrade Cost

The repository identifies its license as Unlicense and includes a `COPYING` file. The README also states that the source code and binary releases are freely redistributable in any form. This describes the project's stated licensing terms, but it is not legal advice about ownership, compatibility, or liability for damaged media. Users must consider their own preservation obligations and applicable law separately.

Release history lists version 1.23 dated 2025-12-17, version 1.22 dated 2025-03-10, and version 1.21 dated 2024-10-23. The repository's last push was on 2026-06-16. It is not archived. The README's Pipx command refers to `@latest`, however, rather than pinning version 1.23, so the installed revision can change as that moving reference changes.

Upgrade cost depends on the installation route. Windows users receive a packaged executable directory and can obtain a newer release by downloading and replacing host-tool files. Source users deal with Python dependencies, version metadata, a native extension, and stricter Linux compiler flags. The repository does not provide a migration guide, firmware compatibility matrix, or configuration compatibility policy. The release list documents published versions, but it does not explain whether host tools can be upgraded independently of firmware without operational restrictions.

Greaseweazle Versus Filesystem-Level Disk Tools

The closest alternative in approach is a conventional disk-imaging utility that reads a mounted filesystem or translates a drive into a sector-based image before recovery. Greaseweazle instead targets recorded flux data through a purpose-built USB device and separates host tools from firmware. That difference affects both the information available and the setup required. A filesystem-oriented tool can expose files once mounted, but the README does not claim that such a tool can preserve raw magnetic transitions.

Greaseweazle also differs from an offline disk duplicator built around an IDE or USB interface. Its documented interface is the Greaseweazle USB device, and the host package exposes `gw` for controlling it. An offline duplicator normally centers on block-device behavior, while this project places raw floppy flux at the center of its stated function. The repository does not compare read errors, transfer speed, supported capacities, or media formats, so no performance judgment between the approaches is supportable from the documentation.

For a collection whose goal is ordinary file access or block-image duplication, a filesystem-level tool may be simpler because it avoids the hardware, firmware, and raw-writing questions created by Greaseweazle. For preservation work that depends on transitions below the filesystem, that convenience would remove a required layer of detail. Greaseweazle is the specialized choice here, not a general-purpose disk copier.

Editorial conclusion

Adopt Greaseweazle Host Tools if you need the documented raw-floppy hardware and are prepared to follow the wiki for capture, decoding, writing, and device configuration. Do not choose it as a conventional disk-imaging utility without confirming that its supported workflow matches your media and system. Check the connected Greaseweazle firmware, device recognition in the `gw` interface, and the exact read or write procedure for the target disk first.

Frequently asked questions

Official sources

1. Issues
2. keirf/greaseweazle on GitHub
3. License: Unlicense
4. README
5. Releases