GitHub - drdpj/CPMDiskWrangler: A Qt6 application for wrangling CP/M disk images

CP/M Disk Wrangler

View and edit CP/M disc images. It reads raw sector dumps, ImageDisk, standard and extended DSK (the format CPCEMU introduced), and TeleDisk images, works out the disc's format from its contents, and lets you add, extract, view, rename and delete files, change user numbers and attributes, set CP/M 3 labels, convert between image types, and make new discs in about 140 formats. Files can be dragged between discs, to and from your desktop, and to and from Acorn Disk Wrangler and other tools that support the retro-files drag-and-drop format.

Download

Get the latest build for Windows, macOS or Linux from the Releases page.

• Windows (10 or later, 64-bit): run the ...-setup.exe installer, which installs into Program Files and adds the program to the Start menu (without administrator rights, choose to install it only for you), or unzip the .zip anywhere and run cpmdiskwrangler.exe. Neither is signed, so Windows may warn the first time: choose More info, then Run anyway.
• macOS (12 or later, Intel or Apple Silicon): open the .dmg and drag the app to Applications. It isn't signed by Apple, so the first time, right-click it and choose Open.
• Linux (x86_64):
  • Ubuntu 22.04 or later, Debian 12 or later: install the .deb, which uses the system's Qt and puts the program in the applications menu with its icon: sudo apt install ./cpmdiskwrangler-<version>-linux-amd64.deb (the ./ matters; Ubuntu's App Center may not open a downloaded .deb). Remove it with sudo apt remove cpmdiskwrangler.
  • Any other Linux: the .AppImage runs as it is - make it executable (chmod +x) and start it. It doesn't add itself to the applications menu, so docks show a generic icon for it unless a tool such as Gear Lever or AppImageLauncher integrates it.

Help > About shows the version, and Help > Licences the licences of the program and everything distributed with it.

What it opens

A file's type comes from what is in it, never from its name: many emulators use .dsk for a plain sector dump, so a .dsk file is opened as a DSK image only if it carries a DSK header, and as a raw image otherwise.

It copes with interleaved and rotated tracks, with discs whose track 0 is single density (FM) and the rest double density (Osborne, Research Machines 480Z, Vector Graphic), and with double-sided discs that hold a separate filesystem on each side (shown as Side 0 and Side 1). New double-sided Research Machines discs can be made too: tick "Double-sided" in File > New disc image (ImageDisk, DSK or raw).

It also opens and writes Torch CP/N discs (the Torch Z80 second processor for the BBC Micro). Their files are CP/M files, but the disc keeps them its own way rather than in a CP/M directory; the program recognises such a disc and handles it like any other, except that it has no labels or time stamps and keeps sizes in whole 128-byte records.

How it finds the format

A CP/M disc doesn't record its own layout, so the program tries the possibilities - block size, directory size, reserved tracks, skew, side order - and keeps the reading that makes sense of the directory and the files. Known formats count for more: about 140 are built in, including cpmtools' library, the Amstrad CPC, PCW and +3, Kaypro, Osborne, Research Machines 480Z, Vector Graphic, Sharp, Acorn's Z80 second processor and Torch CP/N.

Tools > Disc format shows the ranked readings and their evidence, lets you pick one yourself (it's remembered for that file), and copies any of them as a cpmtools diskdef. Tools > Add a diskdefs file adds your own definitions.

To keep a wrong guess from damaging a disc, a disc can only be changed when the reading is certain: a known format with no close rival, one you've confirmed, or a disc made by this program. Otherwise it opens read-only and the status bar says why.

Using it

• One disc per window. File > Open opens a new window if this one already has a disc in it. Dropping disc images on an empty window opens them; dropped on a window with a disc, they're copied onto it as files.

• Files are grouped by user number. Drop files on a User N row to put them in that user number. Host folders named user3, user 3, u3 or 3 go to that user number; other folders are flattened.

• Add files by dropping them from your file manager, or copy them there and Paste them here. Names become CP/M 8.3 (upper case; characters CP/M can't use become -).

• Extract files by dragging them out to your desktop or another program, or by copying them here and pasting them there. Dragged or pasted into a tool that supports retro-files, they keep their user number and attributes (see below).

• Copy and Paste (Edit menu, or your system's usual keys: Ctrl+C / Ctrl+V, Cmd+C / Cmd+V on a Mac) work between windows, between the two sides of a disc, with Acorn Disk Wrangler and with your file manager. A paste goes to the selected user number (none selected: each file keeps its own).

• View (double-click, F3): text up to the end-of-file mark (optionally ignoring WordStar's high bit), or hex.

• Rename (F2), Properties (Alt+Enter) for attributes (R/O, SYS, ARC, F1'-F4') and user number, for one file or many. Edit > Disc label for CP/M 3 discs.

• Tools > Check disc checks the directory; Disc information shows the geometry and format.

• File > New disc image: any format in the library, as ImageDisk, extended DSK, standard DSK or raw, optionally with CP/M 3 time stamps and a label. File > Save As converts between image types (e.g. TeleDisk to ImageDisk).

• Save (Ctrl+S). Nothing is written until you save; the directory is checked first, it won't save if the file was changed by something else meanwhile, and a .bak copy of the previous file is kept (Tools; on unless you turn it off).

• Tools > Allow lower-case file names (also in the menu of the Names: button at the bottom right of the window, which says which character set and case rule the disc is shown with) lets names keep lower-case letters, for discs that hold them (COMAL's do). CP/M's BDOS does not reject lower case: a program can put lower-case letters in a file control block and Make File will store them, and the directory search compares the bytes it is given, so readme.txt and README.TXT are different files. It is only the convention that names are upper case, because the command processor upper-cases what you type, so a lower-case file can't be named at the prompt. The box is ticked for a disc with any lower-case name and unticked otherwise, remembered per disc. Ticked, names you add, rename or drop from the host keep their case, so a name goes out to the host and back unchanged; unticked, they are made upper case, as CP/M's own tools would. When extracting, names with lower-case letters keep them, upper-case names are written in lower case unless that would clash with another name, and only a host that can't tell the two apart (Windows, macOS) adds _2, which is taken off again when the files are dropped back.

• Tools > Character set for names and text chooses the national variant of ASCII a disc was written in (Danish/ Norwegian, Swedish/Finnish, German, French, Italian, Spanish, Portuguese). On those machines [ \ ] { | } were the letters Æ Ø Å æ ø å and so on, so a file called br|kregning is really brøkregning. With a set chosen, names and text files are shown, exported and imported as Unicode; the disc itself is unchanged. The program suggests it when names or text use those characters between letters, and remembers the choice for that disc. # and $ are not mapped, as the sets differ on them and they appear in too many ordinary names. Dragging between programs follows retro-files: the name travels as the disc holds it, so files moved between CP/M discs keep their names exactly whatever set each disc uses; only the name of a file written to the host is shown in the national letters.

Settings, and carrying the program with you

Options (Tools menu), the last folders used and the formats you confirmed for each image are saved in the usual place for your system: the registry (HKEY_CURRENT_USER\Software\cpmdiskwrangler\cpmdiskwrangler) on Windows, ~/Library/Preferences/com.cpmdiskwrangler.cpmdiskwrangler.plist on macOS, ~/.config/cpmdiskwrangler/cpmdiskwrangler.conf on Linux. To keep them with the program instead - on a USB stick, say - choose File > Create local config file: it makes cpmdiskwrangler.ini in the program's folder (beside the .exe on Windows, beside the .app on macOS) with a copy of the current settings, and uses it from then on. (Putting an empty file of that name there by hand does the same.) Delete the file to go back to the system's settings. Help > About says which is in use. For the AppImage the file goes beside the .AppImage; a program installed from the .deb or by the Windows installer always uses the system's place, so it doesn't offer this.

Drag and drop between disc tools

Both Wranglers implement retro-files (application/x-retro-files+json), an open format for dragging files out of disc images and into other programs. An ordinary drag between programs carries only a file's name and contents, but a file on a retro disc has more than that, and it matters: an Acorn file's load and execution addresses (without them a program may not run, and they also hold its type and date), access bits, a DFS directory letter, DOS attributes, a CP/M user number. retro-files carries those too. That means:

• Files move between disc tools without losing anything. Drag a file from a disc in one program that supports the format to a disc in another - between Acorn Disk Wrangler and CP/M Disk Wrangler, between two copies of either, or to any other tool that adopts it - and its attributes go with it. The receiving program converts what the destination disc can hold (for example, an Acorn file's lock becomes CP/M's read-only flag) instead of guessing from a bare file.
• Nothing else breaks. The same drag also carries ordinary files, so dropping on your desktop, a file manager or any other program works as usual.
• Any tool can join in. It is a small, versioned JSON document, with attributes grouped by filesystem (acorn, fat, cpm): a tool for another kind of disc adds its own group and reads the groups it understands. The specification explains the format and why it exists.

Limitations

• TeleDisk images can't be saved back as TeleDisk, and TeleDisk 1.x "advanced compression" isn't supported.
• A raw image can't hold a disc whose track 0 differs from the rest; use ImageDisk or DSK for those.
• Copy-protected tracks (duplicate sector numbers) are read but never written.
• DateStamper's !!!TIME&.DAT time stamps are kept but not shown; CP/M 3 passwords are kept but not checked.

Building from source

Needs Qt 6 (or Qt 5.15) with its widgets module, and a C++17 compiler.

qmake cpmdiskwrangler.pro && make              # or: cmake -S . -B build && cmake --build build
./cpmdiskwrangler [image ...]                  # each image opens in its own window

See docs/building.md for Windows, macOS, Qt 5, the release builds and how they carry their licences.

Licence

Copyright (C) 2026 Daniel Jameson. Licensed under the GNU General Public License v3.0 or later - see LICENSE. Includes the disc definitions from cpmtools 2.23 (Michael Haardt and contributors, GPL v3 or later); the TeleDisk decoder follows LZHUF by Haruyasu Yoshizaki and Haruhiko Okumura. Uses Qt under the LGPL v3. Everything third-party, and its terms, is listed in THIRD-PARTY-NOTICES.md.

Working on the code? See AGENTS.md: design rules, format notes, detection, tests and pitfalls.