{"id":7642,"library":"pyunpack","title":"pyunpack: Unpack Archive Files","description":"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.","status":"active","version":"0.3","language":"en","source_language":"en","source_url":"https://github.com/ponty/pyunpack","tags":["archive","unpack","extraction","file compression","patool","zip","rar","7z"],"install":[{"cmd":"pip install pyunpack","lang":"bash","label":"Install pyunpack"},{"cmd":"pip install https://github.com/wummel/patool/archive/refs/heads/master.zip","lang":"bash","label":"Install latest patool (recommended)"},{"cmd":"sudo apt-get install unzip unrar p7zip-full","lang":"bash","label":"Install external unarchivers (Debian/Ubuntu example)"}],"dependencies":[{"reason":"Required for unpacking most non-ZIP archive formats. pyunpack uses patool's command-line interface. For latest features and fixes, installing directly from GitHub is recommended due to infrequent PyPI updates.","package":"patool","optional":true},{"reason":"Runtime dependency for managing external process calls made by pyunpack and patool.","package":"easyprocess","optional":false},{"reason":"Runtime dependency for command-line interface generation.","package":"entrypoint2","optional":false}],"imports":[{"symbol":"Archive","correct":"from pyunpack import Archive"}],"quickstart":{"code":"# First, create a dummy archive file for testing (e.g., 'test_archive.zip')\n# For example, create 'hello.txt' with content 'Hello, pyunpack!' and then run:\n# zip test_archive.zip hello.txt\n\nimport os\nimport shutil\nfrom pyunpack import Archive\n\n# Ensure a dummy archive exists and a target directory\narchive_name = 'test_archive.zip'\nextract_dir = 'extracted_files'\n\n# Clean up previous runs if any\nif os.path.exists(extract_dir):\n    shutil.rmtree(extract_dir)\nif os.path.exists(archive_name):\n    os.remove(archive_name)\n\n# Create a dummy file and zip it\nwith open('hello.txt', 'w') as f:\n    f.write('Hello, pyunpack!\\n')\nimport zipfile\nwith zipfile.ZipFile(archive_name, 'w') as zf:\n    zf.write('hello.txt')\nos.remove('hello.txt') # Clean up dummy source file\n\n# Perform the extraction\ntry:\n    print(f\"Extracting '{archive_name}' to '{extract_dir}'...\")\n    Archive(archive_name).extractall(extract_dir)\n    print(\"Extraction successful!\")\n\n    # Verify content\n    extracted_file_path = os.path.join(extract_dir, 'hello.txt')\n    if os.path.exists(extracted_file_path):\n        with open(extracted_file_path, 'r') as f:\n            content = f.read().strip()\n        print(f\"Content of extracted file: '{content}'\")\n    else:\n        print(\"Error: Extracted file 'hello.txt' not found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up created files and directory\n    if os.path.exists(archive_name):\n        os.remove(archive_name)\n    if os.path.exists(extract_dir):\n        shutil.rmtree(extract_dir)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are running pyunpack in a Python 3 environment (Python 3.9+ is officially supported).","message":"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.","severity":"breaking","affected_versions":"0.3 and higher"},{"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`.","message":"The `patool` library, a core dependency, sometimes has an outdated PyPI release. This can lead to issues with newer archive formats or general instability.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"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)"},{"fix":"Run your code with a Python 3 interpreter. pyunpack 0.3 officially supports Python 3.9-3.12.","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.","error":"SyntaxError: invalid syntax (on import line, e.g., `from typing import Optional`)"},{"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`.","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.","error":"pyunpack.PatoolError: patool can not unpack\\n<stderr output indicating patool itself failed>"}]}