A secure, user-friendly desktop application for extracting one or multiple ZIP archives while automatically handling long Windows paths, invalid filenames, duplicate names, and unsafe archive entries.
The application includes a graphical interface, batch extraction, configurable path limits, progress tracking, cancellation, activity logs, timestamp preservation, and protection against Zip Slip path traversal.
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 to reduce collisions
- Replacing Windows-invalid filename characters
- Handling reserved Windows device names
- Blocking absolute paths and parent-directory traversal
- Continuing extraction when an individual entry cannot be processed
- Native desktop interface built with Python and Tkinter
- Add one or multiple ZIP archives
- Scan a folder for all
.zipfiles - 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, andLPT1 - 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
- Display renamed, skipped, completed, and failed entries in an activity log
- Cancel an extraction while it is running
- Open the output directory from the application
- Continue processing other entries when one entry fails
- Run without third-party Python packages
You can add screenshots to a screenshots folder and display them here:
The application is designed to run on:
- Windows 10
- Windows 11
- Windows Server 2019 or later
- macOS 11 or later
- Ubuntu 20.04 or later
- Other modern Linux distributions with Python and Tkinter support
Windows is the primary target because the application specifically addresses Windows path-length and filename restrictions.
- Dual-core processor
- 4 GB RAM
- Python 3.9 or later
- Tkinter support
- Sufficient free disk space for the extracted content
- Quad-core processor
- 8 GB RAM
- SSD storage
- At least twice the compressed archive size available during extraction
- A short output location such as
C:\Extractedwhen processing archives with very deep structures
The source-code version requires:
- Python 3.9 or later
- Tkinter
- Python standard library modules
No external Python package is required to run the application.
The application uses the following standard library modules:
dataclasses
hashlib
os
pathlib
queue
re
shutil
subprocess
sys
threading
time
tkinter
zipfile
-
Download Python from the official Python website:
-
Run the installer.
-
On the first installation screen, select:
Add Python to PATH -
Make sure the optional Tcl/Tk and IDLE component remains selected. Tkinter is normally installed with the official Windows Python distribution.
-
Complete the installation.
-
Open Command Prompt and verify Python:
python --version
-
Verify Tkinter:
python -m tkinter
A small Tkinter test window should open.
If the python command is unavailable, try:
py --version
py -m tkinterInstall a current version of Python from:
https://www.python.org/downloads/
If Homebrew is available, Python can also be installed with:
brew install pythonVerify the installation:
python3 --version
python3 -m tkinterThe Python installer from python.org is generally the simplest choice when Tkinter support is required.
Install Python, Tkinter, and the virtual-environment module:
sudo apt update
sudo apt install python3 python3-tk python3-venv -yVerify the installation:
python3 --version
python3 -m tkintersudo dnf install python3 python3-tkintersudo pacman -S python tk- Open the repository on GitHub.
- Select Code.
- Select Download ZIP.
- Extract the downloaded repository ZIP.
- Open the extracted project folder.
git clone https://github.com/YOUR-USERNAME/zip-extractor-path-fix.git
cd zip-extractor-path-fixReplace YOUR-USERNAME with your GitHub username.
Double-click:
run.bat
python app.pyIf python is not recognized but the Python launcher is installed:
py app.pypython3 app.py- Start the application.
- Select Add ZIP files to choose individual archives, or select 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.
Each ZIP archive is extracted into a separate folder based on the archive name. If that destination already exists and overwrite mode is disabled, the application creates a uniquely numbered destination folder.
The default maximum path length is:
220 characters
This conservative value leaves room for filesystem and application-specific behavior on Windows.
Recommendations:
- Keep
220for general Windows use. - Use a short output path such as
C:\Extractedfor deeply nested archives. - Increase the value only when the operating system and destination filesystem support longer paths.
- Do not set an unnecessarily low value because it can result in more filenames being shortened.
When a path exceeds the configured limit, the application:
- Identifies long path components.
- Shortens the longest component first.
- Preserves the file extension.
- Adds a short SHA-1-based identifier.
- Rechecks the complete destination path.
- Continues shortening only when necessary.
A long filename may be converted into a structure similar to:
quarterly_financial_archive_document__a1b2c3d4.xlsx
The hash makes shortened names more distinguishable than simple truncation.
The application rejects archive entries containing unsafe parent-directory paths such as:
../outside.txt
It also rejects drive-qualified or absolute-style paths that might attempt to write outside the selected extraction folder.
Characters not allowed in Windows filenames are replaced with underscores:
< > : " / \ | ? *
Control characters are also replaced.
Windows device names are adjusted automatically, including:
CON
PRN
AUX
NUL
COM1 to COM9
LPT1 to LPT9
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.
This is the safer default.
- Existing destination archive folders receive a numbered suffix.
- Existing files receive a numbered suffix.
- Existing content is not intentionally replaced.
- Matching files may be replaced.
- Use this option only when replacement is intended.
- Consider backing up important destination folders first.
The application does not request or manage archive passwords through the graphical interface.
Password-protected entries that cannot be read are reported as skipped. Other readable entries may continue to extract.
A Windows executable allows end users to run the application without separately installing Python.
On a Windows computer with Python installed, double-click:
build_windows.bat
The script installs or updates PyInstaller and creates the executable.
Expected output:
dist\ZIP-Extractor-Path-Fix.exe
Install PyInstaller:
python -m pip install --upgrade pyinstallerBuild the executable:
python -m PyInstaller --noconfirm --clean --onefile --windowed --name "ZIP-Extractor-Path-Fix" app.pyUsers running the generated EXE do not need to install:
- Python
- pip
- Tkinter
- PyInstaller
- Any external Python package
The generated executable contains the Python runtime and application code required to launch the program.
Some antivirus products may inspect or temporarily flag newly created unsigned PyInstaller executables. For public distribution, consider code signing the Windows executable.
Run the automated tests from the project folder:
python -m unittest -v test_app.pypython3 -m unittest -v test_app.pyThe included tests cover:
- Invalid character cleanup
- Reserved Windows filename handling
- Zip Slip rejection
- Long-path extraction and shortening
- Successful file-content extraction
zip-extractor-path-fix/
├── app.py
├── build_windows.bat
├── LICENSE
├── README.md
├── requirements.txt
├── run.bat
└── test_app.py
Optional repository directories can be added later:
docs/
screenshots/
.github/ISSUE_TEMPLATE/
.github/workflows/
Python is either not installed or was not added to the system PATH.
Try:
py --versionIf that also fails, reinstall Python and select Add Python to PATH during installation.
On Ubuntu or Debian:
sudo apt install python3-tk -yOn Fedora:
sudo dnf install python3-tkinterOn Windows, reinstall Python using the official installer and ensure Tcl/Tk is selected.
Open Command Prompt in the project folder and run:
python app.pyThe command window should display any Python startup error.
Try the following:
- Choose a shorter destination such as
C:\Extracted. - Reduce the maximum path value from
220to200. - Confirm that the destination allows file creation.
- Avoid extracting directly into a deeply nested OneDrive, SharePoint sync, or network-drive folder.
- Review the activity log for the exact skipped entry and error.
- Select an output folder where the current user has write permission.
- Avoid protected folders such as
C:\WindowsandC:\Program Files. - Close files that may already be open in another application.
- Check whether security software is blocking file creation.
Test the archive with another ZIP utility. If the archive is damaged, some or all entries may be unavailable. The application logs errors and attempts to continue where possible.
ZIP archives can expand to many times their compressed size. Confirm that the destination drive has enough space before extraction.
Modern Windows versions can support longer Win32 paths when the relevant operating-system policy is enabled and the application supports it.
The tool does not require this setting because it actively shortens paths. However, administrators may enable the Windows long-path policy for additional compatibility.
Group Policy location:
Computer Configuration
> Administrative Templates
> System
> Filesystem
> Enable Win32 long paths
This setting may require administrator access and may be controlled by organizational policy.
- Password entry is not currently available in the graphical interface.
- Corrupted archives may extract only partially or fail completely.
- Available disk space is not estimated before extraction.
- Symbolic-link handling depends on how the archive was created and how Python interprets the entry.
- Destination files are not restored automatically if extraction is cancelled midway.
- Some network drives and synchronized folders enforce stricter naming or path rules.
- The program supports ZIP archives only. Other formats such as RAR, 7z, and TAR are not included.
The application runs locally.
- It does not upload archives.
- It does not send filenames to an external service.
- It does not require an account.
- It does not include analytics or telemetry.
- Extracted files remain in the output directory selected by the user.
Contributions, improvements, and bug reports are welcome.
Recommended contribution process:
- Fork the repository.
- Create a feature branch.
- Make and test the changes.
- Update documentation where required.
- Open a pull request with a clear description.
Example:
git checkout -b feature/improved-password-support
git commit -m "Add password entry support"
git push origin feature/improved-password-supportWhen reporting a problem, include:
- Operating system and version
- Python version
- Whether the source-code or EXE version was used
- Maximum path-length setting
- Relevant activity-log message
- A safe sample archive structure, if possible
- Steps required to reproduce the issue
Do not upload confidential archives, private filenames, or sensitive business data to a public GitHub issue.
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
- Configurable filename-shortening rules
- Windows Explorer context-menu integration
- Signed Windows installer
This project is released under the Creative Commons Zero v1.0 Universal dedication, also identified as CC0-1.0.
You may use, copy, modify, and distribute the project for personal or commercial purposes without requesting permission, subject to the terms in the LICENSE file.
The software is provided without warranty.
Always retain a backup of important archives and destination data. Although the application includes path safety, collision handling, and extraction error recovery, no extraction utility can guarantee recovery from corrupted archives, filesystem failures, insufficient storage, permission restrictions, or unexpected system interruption.
If the application is useful:
- Star the repository
- Report reproducible issues
- Suggest improvements
- Contribute documentation or code
- Share the project with users facing Windows path-length problems
Extract ZIP files safely, without path-length headaches.