patool

library4.0.5pypypi✓ verified 22d ago

patool is a portable archive file manager that supports a wide array of formats like 7z, RAR, ZIP, and TAR. It simplifies archive handling by abstracting away the complexities of various underlying compression programs. While it can natively handle formats like TAR, ZIP, BZIP2, LZMA, and GZIP, it often relies on helper applications installed on the system for other formats. The library is actively maintained, with frequent releases, and is currently at version 4.0.4, requiring Python 3.11 or later.

serialization

pip install patool

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PATOOL

patool

serializationpythonv4.0.5

Install

1.6s avg

Import

78ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.081s · 18.8MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.074s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

patoolib

✓ import patoolib

✗ import patool

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

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.")

patool --version

Debug

Known issues

breakingVersion 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.

affects: 4.0.0 and later

gotchaFor 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.

affects: All versions

gotchaThe 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.

affects: All versions

gotchaBy 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.

affects: All versions

gotchaWhile `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.

affects: All versions

Errors

Common errors & fixes

PatoolError: could not find an executable program to extract format rar; candidates are (rar,unrar,7z)

patool requires external helper applications (like `unrar`, `7z`, `zip`, `unzip`) to handle most archive formats, and this error occurs when it cannot locate the necessary program in the system's PATH.

fix

Install the required helper application for the specific archive format (e.g., `sudo apt-get install unrar` for RAR files on Linux, or install 7-Zip/WinRAR on Windows and ensure they are in your system's PATH).

ModuleNotFoundError: No module named 'patoolib'

The `patool` library (specifically the `patoolib` package) is not installed in the Python environment being used, or the Python environment is not correctly configured.

fix

Install the `patool` library using pip: `pip install patool`. If using a virtual environment, ensure it's activated.

ValueError: patool not found! Please install patool!

Although `patool` might be installed, the Python environment or the specific execution context (e.g., a script run with a different Python interpreter or a broken PATH) cannot locate the `patool` executable or its associated modules.

fix

Ensure the correct Python interpreter is being used and that `patool` is installed within that environment (`which python` and `pip list` can help). If running in a specific context (like an IDE or a build system), verify its Python environment settings. Reinstalling in a fresh virtual environment often resolves conflicts.

PatoolError: Command `['c:\Rtools\bin\gzip.EXE', '-c', '-d', '--', 'D:\inpath\file.xml.gz', '>', 'D:\outPath\file.xml']` returned non-zero exit status 1.

The external helper application invoked by patool (e.g., `gzip`, `unrar`, `7z`) encountered an error during its operation and exited with a non-zero status, indicating a failure. This could be due to a corrupt archive, insufficient permissions, or issues with the helper application itself.

fix

Increase patool's verbosity (`verbosity=1` or `verbosity=2` in `extract_archive`) to get more detailed output from the helper application, which might reveal the specific cause of the failure. Verify the archive's integrity and ensure the helper application works correctly when run manually with the same command.

Upgrade

Version history

4.0.5latest on PyPI · released May 18, 2026

Audit

Dependencies

argcompleteoptionalProvides tab-completion for the command-line tool.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/wummel/patool ↗

packagehttps://pypi.org/project/patool/ ↗

homepagehttps://wummel.github.io/patool/ ↗