pyunpack: Unpack Archive Files

0.3 · active · verified Thu Apr 16

pyunpack is a Python library that provides a simple interface for unpacking various archive file formats such as ZIP, RAR, and 7z. It primarily acts as a wrapper around the `patool` library, which in turn leverages external command-line unarchiving tools. If `patool` is not available or cannot handle a specific format, `pyunpack` falls back to Python's built-in `zipfile` module for ZIP archives. The current stable version is 0.3, released in June 2022, with an infrequent release cadence.

Common errors

```
pyunpack.PatoolError: patool can not unpack\npatool error: error extracting /path/to/archive.rar: could not find an executable program to extract format rar; candidates are (rar,unrar,7z)
```
cause The external command-line tool required to unpack the specific archive format (e.g., `unrar`, `7z`) is not installed on the system or is not accessible in the system's PATH.

fix Install the appropriate external unarchiver program for the format you are trying to extract. For `.rar` files, install `unrar`. For `.7z` files, install `7zip` (e.g., `p7zip-full` on Linux). Ensure the executable is in your system's PATH.
```
SyntaxError: invalid syntax (on import line, e.g., `from typing import Optional`)
```
cause You are attempting to use `pyunpack` version 0.3 or later with a Python 2.x interpreter. These versions utilize Python 3-specific syntax (like type hints) that Python 2 does not understand.

fix Run your code with a Python 3 interpreter. pyunpack 0.3 officially supports Python 3.9-3.12.
```
pyunpack.PatoolError: patool can not unpack\n<stderr output indicating patool itself failed>
```
cause Even if `patool` is installed via `pip`, it might be an outdated version from PyPI, or `patool` itself might be failing to locate or execute the underlying system unarchivers.

fix First, ensure all external unarchivers are correctly installed and in PATH (see first problem). If the issue persists, try installing `patool` directly from its GitHub repository to get the latest version: `pip install https://github.com/wummel/patool/archive/refs/heads/master.zip`.

Warnings

gotcha pyunpack relies heavily on external command-line tools (like `unrar`, `7z`, `unzip`) via `patool`. If these tools are not installed on your system or are not in the system's PATH, pyunpack will fail to unpack the corresponding archive formats. It can only handle ZIP files natively without external tools.
Fix: Install the necessary command-line unarchivers (e.g., `sudo apt-get install unrar p7zip-full` on Linux) and ensure they are discoverable in your system's PATH.
breaking Older documentation and PyPI pages might incorrectly state that Python 3 is not supported. Modern versions of pyunpack (0.3) support Python 3.9, 3.10, 3.11, and 3.12. Attempting to use pyunpack 0.3 with Python 2.x will result in `SyntaxError` due to type hints and other Python 3-specific syntax.
Fix: Ensure you are running pyunpack in a Python 3 environment (Python 3.9+ is officially supported).
gotcha The `patool` library, a core dependency, sometimes has an outdated PyPI release. This can lead to issues with newer archive formats or general instability.
Fix: If encountering issues with `patool`, consider installing it directly from its GitHub repository: `pip install https://github.com/wummel/patool/archive/refs/heads/master.zip`.

Install

pip install pyunpack Install pyunpack
pip install https://github.com/wummel/patool/archive/refs/heads/master.zip Install latest patool (recommended)
sudo apt-get install unzip unrar p7zip-full Install external unarchivers (Debian/Ubuntu example)

Imports

Archive
```
from pyunpack import Archive
```

Quickstart

This quickstart demonstrates how to unpack a simple ZIP archive using `pyunpack`. It includes steps to create a dummy ZIP file, extract its contents, verify the extraction, and clean up afterwards. For non-ZIP formats, ensure `patool` and the corresponding external unarchiving utilities are installed and accessible in your system's PATH.

# First, create a dummy archive file for testing (e.g., 'test_archive.zip')
# For example, create 'hello.txt' with content 'Hello, pyunpack!' and then run:
# zip test_archive.zip hello.txt

import os
import shutil
from pyunpack import Archive

# Ensure a dummy archive exists and a target directory
archive_name = 'test_archive.zip'
extract_dir = 'extracted_files'

# Clean up previous runs if any
if os.path.exists(extract_dir):
    shutil.rmtree(extract_dir)
if os.path.exists(archive_name):
    os.remove(archive_name)

# Create a dummy file and zip it
with open('hello.txt', 'w') as f:
    f.write('Hello, pyunpack!\n')
import zipfile
with zipfile.ZipFile(archive_name, 'w') as zf:
    zf.write('hello.txt')
os.remove('hello.txt') # Clean up dummy source file

# Perform the extraction
try:
    print(f"Extracting '{archive_name}' to '{extract_dir}'...")
    Archive(archive_name).extractall(extract_dir)
    print("Extraction successful!")

    # Verify content
    extracted_file_path = os.path.join(extract_dir, 'hello.txt')
    if os.path.exists(extracted_file_path):
        with open(extracted_file_path, 'r') as f:
            content = f.read().strip()
        print(f"Content of extracted file: '{content}'")
    else:
        print("Error: Extracted file 'hello.txt' not found.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up created files and directory
    if os.path.exists(archive_name):
        os.remove(archive_name)
    if os.path.exists(extract_dir):
        shutil.rmtree(extract_dir)

view raw JSON →