patool

Warnings

• breaking Version 4.0.0 introduced a change in behavior when a program does not support a compression type; patool now tries to find other programs instead of failing. This primarily affects users relying on unofficial API usage that might have expected the previous failure mode.
  Fix: Review code that might implicitly rely on `patool` failing when the primary program doesn't support a compression type. Consider explicitly specifying the `program` argument in `patoolib` functions if specific external tools are desired.
• gotcha For many archive formats (e.g., RAR, 7z, XZ), `patool` relies on external command-line tools to be installed on the system (e.g., `unrar`, `7z`, `xz`, `tar`). Without these helper applications in the system's PATH, `patool` will raise a `PatoolError` for those formats.
  Fix: Install the appropriate command-line utilities for the archive formats you intend to use. For example, on Linux, `sudo apt-get install unrar p7zip-full xz-utils`. On Windows, you might need to manually install these tools and add their executable directories to your system's PATH environment variable.
• gotcha The correct way to import the library for programmatic use is `import patoolib`. Importing `patool` directly (e.g., `import patool`) will result in an `ImportError` or `ModuleNotFoundError`.
  Fix: Always use `import patoolib` to access the library's functions.
• gotcha By default, `patoolib` functions like `extract_archive` are `interactive` (True). This means they might wait for user input if the underlying compression program requires it (e.g., for a password). In automated scripts, this can lead to indefinite hangs.
  Fix: For non-interactive environments, set the `interactive=False` parameter in `patoolib` function calls (e.g., `patoolib.extract_archive('archive.rar', outdir='/tmp', interactive=False)`) or use the `--non-interactive` global option for the command-line tool. You can also provide passwords via the `password` argument if applicable.
• gotcha While `patool` requires Python >= 3.11, some advanced features or native support for certain formats may depend on newer Python versions. For instance, native support for the ZSTANDARD archive format is enabled with Python >= 3.14.
  Fix: Ensure your Python environment meets the minimum `3.11` requirement. If you encounter issues with specific formats or wish to leverage the latest features, consider using Python 3.14 or newer.

Install

• pip install patool Install patool
• pip install 'patool[argcompletion]' Install with Bash autocompletion

Imports

• patoolib

  import patoolib

  The Python module is named `patoolib`, not `patool`.

Quickstart

This example demonstrates how to create and extract a ZIP archive programmatically using `patoolib`. It first creates a dummy text file, archives it into a .zip file, then extracts the contents to a new directory, and finally cleans up the created files and folders. Ensure you have the necessary system-level archiving tools (like `zip`/`unzip`) installed if you use formats not natively supported by patool.

import patoolib
import os

# Create a dummy file for archiving
dummy_file_path = 'my_document.txt'
with open(dummy_file_path, 'w') as f:
    f.write('This is a test document for patool.\n')
    f.write('It contains some arbitrary text.')

archive_name = 'my_archive.zip'
extract_dir = 'extracted_content'

print(f"Creating archive: {archive_name}")
patoolib.create_archive(archive_name, (dummy_file_path,))

print(f"Extracting archive '{archive_name}' to '{extract_dir}'")
os.makedirs(extract_dir, exist_ok=True)
patoolib.extract_archive(archive_name, outdir=extract_dir)

print(f"Contents of '{extract_dir}':")
for root, dirs, files in os.walk(extract_dir):
    for name in files:
        print(os.path.join(root, name))

# Clean up dummy files and directory
os.remove(dummy_file_path)
os.remove(archive_name)
os.remove(os.path.join(extract_dir, dummy_file_path))
os.rmdir(extract_dir)
print("Cleaned up.")