winddrescue

winddrescue is a Windows command-line rescue copier for damaged files or devices. It is designed for cases where a normal copy stops on read errors, such as a video file stored across weak or bad sectors.

Windows rescue copy tool inspired by GNU ddrescue's recovery strategy, with a GUI, resumable mapfiles, drag-and-drop source selection, and optional portable or installer builds.

It writes every readable byte to the destination, leaves unreadable areas as zero-filled gaps, and keeps a mapfile so you can stop and resume without starting over. For video files, this often produces an output file with the same length as the original, allowing media players or repair tools to use the readable parts.

This project is a from-scratch Windows implementation inspired by GNU ddrescue's documented rescue strategy:

• copy large good areas first
• keep a persistent mapfile
• trim failed ranges at the edges
• scrape remaining failed ranges sector by sector
• optionally retry bad sectors

It does not include GNU ddrescue source code.

References:

• GNU ddrescue home page: https://www.gnu.org/software/ddrescue/ddrescue.html
• GNU ddrescue manual: https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html

Requirements

• Windows
• Python 3

The current implementation uses Win32 CreateFileW, ReadFile, and WriteFile through Python ctypes.

Features

• Rescue-copy damaged files while preserving readable data
• Resume interrupted jobs with ddrescue-style mapfiles
• Windows GUI for files and folders
• Drag-and-drop support from Explorer into the source list
• Verified move mode that deletes the source only after a clean copy
• Portable .exe and installer builds for users without Python

Screenshots

Main UI

Source Selection Area

Self-Test

Run this from the project directory:

python .\tests\selftest.py

The self-test creates a sample file, simulates a 4 KiB unreadable sector, checks that the destination is zero-filled only for that range, then reruns from the same mapfile to verify resume can restore the range when it becomes readable.

Optional Standalone EXE

Prebuilt release files are in release\:

release\winddrescue-portable.zip
release\winddrescue-installer.exe

The portable ZIP contains winddrescue-ui.exe, winddrescue.exe, and this README. Extract it anywhere and run winddrescue-ui.exe.

The installer installs to:

%LOCALAPPDATA%\Programs\winddrescue

It creates a Desktop shortcut named winddrescue and a Start Menu shortcut. It also writes an uninstall entry under Windows Apps & Features for the current user.

To rebuild the release packages from source:

.\build_release.ps1

If you want a single-file executable, install PyInstaller and build it:

python -m pip install --user pyinstaller
python -m PyInstaller --onefile --name winddrescue .\winddrescue.py
python -m PyInstaller --onefile --windowed --name winddrescue-ui .\winddrescue_ui.py

The executables will be written under dist\.

Release Build

To regenerate branding assets, screenshots, portable packages, and the Windows installer:

.\build_release.ps1

That script rebuilds:

• dist\winddrescue.exe
• dist\winddrescue-ui.exe
• release\winddrescue-portable.zip
• release\winddrescue-installer.exe

Code Signing Prep

Unsigned EXEs may trigger SmartScreen warnings. Signing is prepared, but not performed by default.

Prepared assets:

• docs\assets\winddrescue.ico
• resources\windows-version-info.txt
• scripts\sign_release.ps1

After building, sign the EXEs and installer with:

.\scripts\sign_release.ps1 -PfxPath C:\path\to\certificate.pfx -PfxPassword "your-password"

Basic Use

Simple UI

Launch the graphical version:

.\winddrescue-ui.bat

Then choose:

• drag files or folders from Windows Explorer into the Sources list
• Add Files/Folders to open the Explorer-like picker and use Ctrl+click or Shift+click to select multiple files and folders together
• Add Files to select one or more files
• Add Folder to add one folder at a time
• a destination folder, such as a folder on E:
• Copy or Move

You can mix files and folders in the source list. Selected files are copied directly into the destination folder. Selected folders preserve their top-level folder name and internal structure. Mapfiles are stored in _winddrescue_maps inside the destination folder so interrupted copies can resume. When Move is selected, source files are deleted only after they copy cleanly; files with unreadable ranges are left in the source location.

Command Line

.\winddrescue.bat damaged-video.mp4 recovered-video.mp4 recovered-video.map

If the destination already exists and you are starting a new rescue, add --force:

.\winddrescue.bat --force damaged-video.mp4 recovered-video.mp4 recovered-video.map

If the process is interrupted, run the same command again with the same destination and mapfile:

.\winddrescue.bat damaged-video.mp4 recovered-video.mp4 recovered-video.map

Only ranges still marked as unfinished or bad will be revisited.

Useful Options

-b, --block-size SIZE     large first-pass read size, default 1M
-s, --sector-size SIZE    small trim/scrape/retry read size, default 4096
-r, --retries N           retry passes for bad sectors after scraping, default 1
--reopen-on-error         reopen the source after each read error
--no-trim                 skip edge trimming
--no-scrape               skip sector-by-sector scraping
--size SIZE               copy only this many bytes

Size suffixes use binary units: K, M, G, T, or hex values such as 0x100000.

For a fragile drive, a conservative first pass is:

.\winddrescue.bat --force --no-scrape --retries 0 damaged-video.mp4 recovered-video.mp4 recovered-video.map

Then later, when you are ready to spend more time on weak areas:

.\winddrescue.bat --retries 3 damaged-video.mp4 recovered-video.mp4 recovered-video.map

Raw Devices

You can try Windows device paths if you run the terminal as Administrator:

.\winddrescue.bat \\.\PhysicalDrive1 drive-image.bin drive-image.map

For some devices Windows cannot report the size. In that case pass --size:

.\winddrescue.bat --size 64G \\.\PhysicalDrive1 drive-image.bin drive-image.map

Be careful with raw device paths. The destination should normally be an image file, not another physical drive.

Mapfile Statuses

The mapfile uses ddrescue-style status characters:

?  non-tried
+  rescued
*  non-trimmed failed large block
/  non-scraped range
-  bad-sector

The mapfile is updated during the run and backed up as mapfile.bak when it is rewritten.

Limits

This tool can work around read errors from damaged storage. It cannot repair logical corruption that is already readable, such as broken video headers, damaged codec data, overwritten bytes, or a file that was already truncated.

Unreadable ranges are left as zero bytes in the output. That keeps file offsets stable, which is useful for video playback and later repair attempts.

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.