
magic-extractor v1.3.1
Universal Windows extraction tool that detects unknown files and routes them to the right bundled extractor.
Magic Extractor
Description
Magic Extractor is a universal extraction tool for Windows that identifies a file with several detectors and routes it to the right bundled extractor. It aims to cover mainstream compression formats, the installers you actually see today, and a range of less common archivers.
It auto-detects 80+ formats — archives, installers, disk images, forensic
images (EWF/AFF/AD1), disc images, mail stores and modern codecs. See
formats.md for the full list.
Quick Start
Download the latest release, unzip it, and run:
magic-extractor.exe extract mystery.bin
See Examples for identify, list, carve, --recursive and --bruteforce.
Project Structure
src/cli: the command-line tool.bin: bundled detector and extractor binaries.detectors: DIE, Magika, binwalk (TrID's defs are converted todata/signatures.json).extractors: 7-Zip (plus 7-Zip ZS as a fallback), unrar, unace, unshield, lessmsi, dark (WiX), and more.
data: routing data generated from the handlers (see below).formats: one handler module per format family.
src/gui: optional tkinter front-end that wraps the CLI (see GUI).icons: Fluent icons baked into PNGs for light and dark mode.
test: unit tests, the format and engine batteries, and sample files per format.tools: developer tooling —generate_data.py(builds the routing data from the handlers) andgenerate_icons.py(bakes the GUI icons).update: the updater config and scripts that refresh the bundled binaries.docs: supported formats, how to add a handler, third-party notices.
The compiled build keeps bin/, data/ and config.ini external to the exe so
they can be updated with a file swap; cli_paths.py finds them beside the
executable (frozen) or under src/cli/ (dev).
How detection works
For normal extraction, detectors run in this order with early-exit — the first one that yields a known handler wins (cheapest first, so the ML model is usually skipped):
- puremagic — pure-python, no subprocess; a cheap MIME check for well-formed archives.
- built-in signatures — magic-byte patterns in
data/signatures.json; names archivers the engines miss (bcm, dgca, kgb, uharc, alzip, freearc, ...) with no external process. - DIE (Detect It Easy) — signature engine; the specialist for installers, PE and SFX.
- binwalk — short type keys (cpio, lzma, ...) and embedded content.
- Magika — Google's AI content-type detector, as a catch-all.
Each detector contributes uniquely (they are complementary, not redundant): the signature DB names archivers the engines miss, DIE handles installers/PE, binwalk catches a few types the others miss, puremagic/Magika cover MIME.
PureMagic 2.x also provides content-aware deep scanning when it receives the full
file. Full-file analysis is the default; the optional --fast-check modifier
passes only the first 64 KiB when startup speed matters more than deep inspection.
Each handler declares its own indicators via detection_mimes() /
detection_names() / detection_signatures(); tools/generate_data.py compiles
these into data/handlers.json and data/signatures.json (with an optional
data/extra_detections.json merged on top). TrID is not used.
Note: any format whose signature is missing from puremagic's
magic_data.json(or that puremagic reports only as a genericapplication/octet-stream) must declare a customdetection_signatures()entry in its handler — otherwise it will not be detected by content.
--bruteforcedisables early-exit: every detector runs and each detected handler is tried in turn (useful when the first guess is wrong).- Executables also get the SFX and installer handlers (RAR, ACE, ARC, KGB, UHARC, Inno Setup, BitRock, Clickteam) as fallback candidates; each one rejects files that are not its own, so the chain moves on to the next.
- The
carvesubcommand additionally uses binwalk's offset map to extract archives embedded at arbitrary offsets (e.g. inside firmware images).
The detection → handler routing map lives in data/handlers.json (generated, loaded
at runtime). A key can map to several handlers, tried in order until one succeeds:
e.g. 7-Zip first, then 7-Zip ZS for what mainline 7-Zip cannot open (SquashFS with
LZ4, NSIS with ZSTD). A generic-token blacklist lives in data/detection_blacklist.json.
Supported Formats
See formats.md for the full list of formats and their handlers.
Adding a format
To add support for a new format, see docs/adding-a-handler.md — the end-to-end guide (handler class, detection declaration, DIE/TrID lookup, magic signatures, regenerating the routing data, bundling the tool, and testing).
Installation (from source)
Most users just download the release (see Quick Start). To run from source: Python 3.12 or newer is required.
git clone <repo-url>
cd magic-extractor
pip install -r src/cli/requirements.txt
Usage
Magic Extractor uses subcommands:
python src/cli/main.py extract <path> [output_dir] [options] # detect and extract
python src/cli/main.py identify <path> # report type + candidate handlers
python src/cli/main.py list <path> # list archive contents
python src/cli/main.py carve <path> [output_dir] [options] # carve embedded archives (binwalk offsets)
A bare path with no subcommand defaults to extract (backward compatible), and
options may come before the path or the subcommand:
python src/cli/main.py <path> <output_dir> [options]
python src/cli/main.py --debug <path>
python src/cli/main.py --version
--debug and --fast-check work with every subcommand; --password with
extract, list and carve.
<path> can be a folder for every subcommand: its files (not subfolders) are
processed one by one. Each file gets its own output folder: <stem>_extracted
(next to the file, or under output_dir when given), or <name>_extracted when
two files share a stem.
If the output folder already has files, extract writes to a new
<folder>_<YYYYmmdd-HHMMSS> instead of mixing with or overwriting the earlier
result; --merge-output extracts into the existing folder instead, overwriting
files and folders with the same names (the GUI does this when the destination is
locked). The archive being extracted is never overwritten. Each handler attempt
runs in its own temporary folder, so a failed attempt never leaves partial files
behind.
Exit codes: 0 success; 1 failure — nothing could be extracted, a file of a
folder run failed, a folder had no files, or --delete-source could not delete
the source; 2 invalid arguments; 3 extracted with errors — the tool reported a
failure but most of the content was extracted (e.g. symbolic links in a Linux image
cannot be created on Windows), so it is kept in the output folder and the source is
not deleted. With --recursive, nested archives that cannot
be extracted are reported as warnings and do not change the exit code (many
extracted files, e.g. every DLL of an installer, look like candidates).