Overview
ZIP archives can contain deeply nested folders or very long filenames. On Windows, these entries may fail during extraction because the complete destination path exceeds the supported path length. Archives can also contain characters that are not permitted in Windows filenames or unsafe entries that attempt to write files outside the selected destination.
ZIP Extractor with Path Fix addresses these issues automatically by shortening paths only when required, retaining recognizable portions of filenames, adding deterministic hashes to shortened names, replacing invalid filename characters, handling reserved Windows device names, and blocking absolute paths and parent-directory traversal.
Key Features
- Native desktop interface built with Python and Tkinter
- Add one or multiple ZIP archives
- Scan a folder for all .zip files
- Extract every archive into its own destination folder
- Select a custom output directory
- Configure the maximum permitted path length
- Automatically shorten long folders and filenames
- Use hash-based naming to reduce accidental collisions
- Clean invalid Windows filename characters
- Handle reserved names such as CON, PRN, AUX, NUL, COM1, and LPT1
- Protect against Zip Slip and path traversal entries
- Optionally overwrite existing files
- Preserve original file timestamps when possible
- Run extraction in a background thread so the interface remains responsive
- Show overall extraction progress
- Cancel an extraction while it is running
- Open the output directory from the application
- Run without third-party Python packages
System Requirements
Minimum: Dual-core processor, 4 GB RAM, Python 3.9 or later, Tkinter support, sufficient free disk space.
Recommended: Quad-core processor, 8 GB RAM, SSD storage, at least twice the compressed archive size available during extraction.
The application uses only Python standard library modules: dataclasses, hashlib, os, pathlib, queue, re, shutil, subprocess, sys, threading, time, tkinter, zipfile.
Installation
Option 1: Download from GitHub
- Open the repository on GitHub.
- Select Code †’ Download ZIP.
- Extract the downloaded repository ZIP.
- Open the extracted project folder.
Option 2: Clone with Git
git clone https://github.com/PeaBox-Lab/zip-extractor-with-path-fix.git
cd zip-extractor-with-path-fix
Running the Application
Windows
double-click run.bat
# or:
python app.py
macOS and Linux
python3 app.py
How to Use
- Start the application.
- Select Add ZIP files to choose individual archives, or Add folder to scan a folder for ZIP files.
- Review the archive list.
- Select an output directory.
- Keep the default maximum path length of 220, or enter another value.
- Choose whether existing files should be overwritten.
- Choose whether original timestamps should be preserved.
- Select Extract all.
- Monitor the progress bar and activity log.
- Select Open output folder when extraction is complete.
The default maximum path length is 220 characters, a conservative value that leaves room for filesystem and application-specific behavior on Windows.
Security Features
Zip Slip protection
The application rejects archive entries containing unsafe parent-directory paths such as ../outside.txt, and drive-qualified or absolute-style paths that might attempt to write outside the selected extraction folder.
Invalid filename cleanup
Characters not allowed in Windows filenames are replaced with underscores: < > : " / \ | ? *. Control characters are also replaced.
Reserved Windows names
Windows device names are adjusted automatically, including CON, PRN, AUX, NUL, COM1 to COM9, LPT1 to LPT9.
Collision handling
If a file or destination already exists and overwrite mode is disabled, the application generates a numbered alternative name rather than silently replacing the existing item.
Building a Standalone Windows EXE
Double-click build_windows.bat to install PyInstaller and create the executable at dist\ZIP-Extractor-Path-Fix.exe.
python -m pip install --upgrade pyinstaller
python -m PyInstaller --noconfirm --clean --onefile --windowed --name "ZIP-Extractor-Path-Fix" app.py
End users running the generated EXE do not need to install Python, pip, Tkinter, PyInstaller or any external Python package.
Troubleshooting
- python is not recognized: Reinstall Python and select Add Python to PATH.
- Tkinter is missing: On Ubuntu/Debian run sudo apt install python3-tk -y.
- Application does not open: Run python app.py from Command Prompt to see startup errors.
- A path still cannot be extracted: Try a shorter destination such as C:\Extracted, or review the activity log.
Roadmap
Potential future enhancements include drag-and-drop archive selection, password entry for encrypted ZIP files, dry-run preview before extraction, exportable extraction reports, dark mode, destination disk-space checks, support for TAR and other archive formats, Windows Explorer context-menu integration and a signed Windows installer.