Skip to main content

exarch

PyPI Python CI License

Memory-safe archive extraction and creation library for Python.

Important: exarch is designed as a secure replacement for vulnerable archive libraries like Python's tarfile, which has known CVEs with CVSS scores up to 9.4.

This package provides Python bindings for exarch-core, a Rust library with built-in protection against common archive vulnerabilities.

Installation

pip install exarch

Tip: Use uv pip install exarch for faster installation.

Alternative Package Managers

# Poetry
poetry add exarch

# Pipenv
pipenv install exarch

Requirements

  • Python >= 3.10

Quick Start

Extraction

import exarch

result = exarch.extract_archive("archive.tar.gz", "/output/path")
print(f"Extracted {result.files_extracted} files")

Creation

import exarch

result = exarch.create_archive("backup.tar.gz", ["src/", "Cargo.toml"])
print(f"Created archive with {result.files_added} files")

Usage

Basic Extraction

import exarch

result = exarch.extract_archive("archive.tar.gz", "/output/path")

print(f"Files extracted: {result.files_extracted}")
print(f"Bytes written: {result.bytes_written}")
print(f"Duration: {result.duration_ms}ms")

With pathlib.Path

from pathlib import Path
import exarch

archive = Path("archive.tar.gz")
output = Path("/output/path")

result = exarch.extract_archive(archive, output)

Custom Security Configuration

import exarch

config = exarch.SecurityConfig()
config = config.with_max_file_size(100 * 1024 * 1024)  # 100 MB

result = exarch.extract_archive("archive.tar.gz", "/output", config)

Verifying Payload Integrity

verify_archive checks security only by default and reports integrity_status as "SKIPPED". Opt in to decode the payload and verify checksums:

import exarch

options = exarch.VerificationOptions().with_integrity_check()  # 500 MiB budget
report = exarch.verify_archive("archive.zip", options=options)

print(report.integrity_status)  # "OK", "FAILED", "INCOMPLETE" or "SKIPPED"

Note: "INCOMPLETE" means part of the payload was not verified (budget, resource limit, solid 7z archive while allow_solid_archives is off, TAR without an end-of-archive marker); it comes with a Medium issue, so status is at least "WARNING". With the check on, a TAR entry whose content fails to decode raises InvalidArchiveError.

Archives in Memory

list_archive_bytes, verify_archive_bytes and extract_archive_to_memory take the archive as bytes or a binary file object. The format is detected from the leading bytes, or stated with format ("Tar", "TarGz", "TarBz2", "TarXz", "TarZst", "Zip", "SevenZ"). Nothing is written to disk.

import exarch

data = open("archive.tar.gz", "rb").read()

manifest = exarch.list_archive_bytes(data)
report = exarch.verify_archive_bytes(data)

result = exarch.extract_archive_to_memory(data, max_bytes=64 * 1024 * 1024)
for entry in result.entries:
    print(entry.path, entry.kind)  # "file", "directory" or "symlink"
    if entry.kind == "file":
        content = entry.data  # bytes

A file object is read from its current position. If it is seekable() every format works; otherwise only TAR (plain or compressed) can be read. An exception raised by the object propagates unchanged instead of becoming a verdict.

with open("archive.tar.gz", "rb") as f:
    manifest = exarch.list_archive_bytes(f)

Note: max_bytes caps payload plus path bytes plus 256 per entry and defaults to the config's max_total_size; exceeding it raises QuotaExceededError. path_model="portable" validates names against the strictest rules of every platform instead of this host's.

list_archive_bytes_with_progress, verify_archive_bytes_with_progress and extract_archive_to_memory_with_progress take a progress callback (path, total, current, bytes_written) after config; current counts from 1 and total is 0 for TAR. A raising callback does not abort the run; if the run succeeded its exception is raised (with progress_callback_error = True) and the result is discarded.

extract_archive_to_callback(data, on_entry) hands each verified entry to on_entry(entry) instead of collecting them, so memory use is one file at a time (bounded by max_file_size). A file arrives whole, after its size was verified. An exception raised by on_entry stops the extraction and is raised unchanged. A "symlink" entry's target is spelled as the archive stores it, relative to the link. A "hardlink" entry comes last and by reference: its target is the root-relative resolved path of an entry already delivered, a file or an earlier hardlink (a chain is delivered link by link). With skip_duplicates off a path can be delivered more than once and a hardlink refers to the latest delivery; implicit parent directories are not delivered. Entries are provisional: each is delivered as soon as it is verified, so a later failure refuses the archive after earlier entries were already delivered. The gzip CRC of a .tar.gz is verified after the end-of-archive marker, so a corrupt compressed stream refuses the archive only after its entries were delivered.

sizes = {}


def on_entry(entry):
    if entry.kind == "file":
        sizes[entry.path] = len(entry.data)


report = exarch.extract_archive_to_callback(data, on_entry)

create_archive_to_bytes(sources, format) builds an archive in memory and returns a CreatedArchive with data and report:

created = exarch.create_archive_to_bytes(["src/"], "TarGz")
open("src.tar.gz", "wb").write(created.data)

Note: the whole archive is held in memory, up to about 2-3x its size at the peak, and there is no size cap. Sources must be regular files and directories; FIFOs and device files are not supported. Use create_archive for large archives.

Error Handling

import exarch

try:
    result = exarch.extract_archive("archive.tar.gz", "/output")
    print(f"Extracted {result.files_extracted} files")
except exarch.PathTraversalError as e:
    print(f"Blocked path traversal: {e}")
except exarch.ZipBombError as e:
    print(f"Zip bomb detected: {e}")
except exarch.SecurityViolationError as e:
    # e.relaxable_by names the SecurityConfig setting that would admit the entry, or None
    # e.sub_code names the refusal family, e.g. "PATH_NAME", "LINK_POLICY" or "ENCRYPTED"
    print(f"Security violation ({e.relaxable_by}, {e.sub_code}): {e}")
except exarch.InvalidArchiveError as e:
    # e.sub_code is "TAR_AMBIGUITY", "TAR_TRAILER", "ZIP_READER", "LINK_TARGET", "DUPLICATE_ENTRY", "ENTRY_NAME", "DECLARED_SIZE" or "INTEGRITY", else None
    print(f"Invalid archive ({e.sub_code}): {e}")
except exarch.ArchiveError as e:
    print(f"Extraction failed: {e}")

API Reference

extract_archive(archive_path, output_dir, config=None)

Extract an archive to the specified directory with security validation.

Parameters:

Name Type Description
archive_path str | Path Path to the archive file
output_dir str | Path Directory where files will be extracted
config SecurityConfig Optional security configuration
options ExtractionOptions Optional ExtractionOptions().with_atomic(True) / .with_skip_duplicates(...)

Returns: ExtractionReport

Attribute Type Description
files_extracted int Number of files extracted
directories_created int Number of directories created
symlinks_created int Number of symlinks created
bytes_written int Total bytes written
duration_ms int Extraction duration in milliseconds
files_skipped int Number of files skipped (e.g. duplicates)
warnings list[str] Warning messages generated during extraction

Raises:

Exception Description
PathTraversalError Path traversal attempt detected
SymlinkEscapeError Symlink points outside extraction directory
HardlinkEscapeError Hardlink target outside extraction directory
ZipBombError Potential zip bomb detected
QuotaExceededError Resource quota exceeded
SecurityViolationError Security policy violation
UnsupportedFormatError Archive format not supported
UnknownFormatError Archive format cannot be determined from path or magic bytes (subclass of UnsupportedFormatError)
InvalidArchiveError Archive is corrupted
IOError I/O operation failed

create_archive(output_path, sources, config=None, format=None, overwrite=True, durability="synced")

Create an archive from files and directories. The archive is staged in a temporary file next to output_path (its directory must be writable) and renamed into place when complete, so a failed creation leaves the output as it was. format states the format when the extension does not (for example "Zip" for a .whl); overwrite=False refuses any existing output.

Note: create_archive raises FileNotFoundError for missing sources, OutputExistsError (a FileExistsError subclass) when the output exists and overwrite=False, and ValueError for invalid compression levels — matching standard Python conventions.

create_archive and create_archive_with_progress take durability="synced" (the default) or "unsynced". "synced" flushes the archive and its directory entry before returning. "unsynced" skips both, which is faster, but after a crash or power loss a replaced output can be empty or truncated and a new output can be empty, and write-back errors (network filesystems, quotas, delayed allocation) are not reported, so success does not prove the bytes reached the disk. Any other value raises InvalidConfigurationError with setting == "durability".

extract_archive_with_progress(archive_path, output_dir, config, progress)

Extract an archive with a progress callback. The GIL is held when a callback is provided and released otherwise.

Parameters:

Name Type Description
archive_path str | Path Path to the archive file
output_dir str | Path Directory where files will be extracted
config SecurityConfig | None Optional security configuration
progress Callable[[str, int, int, int], None] | None Optional progress callback: (path, total_files, current_file, bytes_written)
import exarch


def on_progress(path: str, total: int, current: int, bytes_written: int) -> None:
    print(f"[{current}/{total}] {path} ({bytes_written} bytes)")


result = exarch.extract_archive_with_progress(
    "archive.tar.gz", "/output", config=None, progress=on_progress
)

If progress raises: extraction is not aborted early — the progress-callback contract has no cancellation signal, so extraction always runs to completion first, and progress is not called again for the remaining entries once it has raised. If extraction otherwise succeeded, progress's own exception propagates unchanged, with files_extracted/bytes_written attributes describing what was written and a progress_callback_error = True marker attribute (check this marker before treating the presence of files_extracted as a partial-extraction signal, since a genuine partial-extraction failure carries the same two attribute names). If extraction also failed, the extraction error takes priority — a raising progress can never mask a security error such as SymlinkEscapeError — and progress's exception is attached as __cause__ instead of being dropped. create_archive_with_progress behaves the same way, using files_added in place of files_extracted.

SecurityConfig

Builder-style security configuration.

config = exarch.SecurityConfig()
config = config.with_max_file_size(100 * 1024 * 1024)  # 100 MB per file
config = config.with_max_total_size(1024 * 1024 * 1024)  # 1 GB total
config = config.with_max_file_count(10_000)  # Max 10k files
config = config.with_max_compression_ratio(50.0)  # Zip bomb threshold
config = config.add_allowed_extension(".txt")  # Extension allowlist
config = config.add_allowed_extension(".md")
config = config.add_banned_component("__MACOSX")  # Skip components
config = config.with_allow_solid_archives(True)  # Allow solid 7z archives
config = config.with_zip_consistency(
    "ignore"
)  # ZIP structure policy: "enforce" (default) or "ignore"
config = config.with_parallel_decode_memory(
    256 * 1024 * 1024
)  # 7z LZMA2 lookahead memory (default 128 MiB); None decodes on one thread
# Each extract/verify call may start up to 16 worker threads and hold its own
# lookahead, so concurrent calls multiply both.

Security Features

The library provides built-in protection against:

Protection Description
Path traversal Blocks ../ and absolute paths
Symlink attacks Prevents symlinks escaping extraction directory
Hardlink attacks Validates hardlink targets
Zip bombs Detects high compression ratios
TAR metadata bombs Bounds GNU long-name/long-link and PAX header record reads
Permission sanitization Strips setuid/setgid bits
Size limits Enforces file and total size limits

Caution: Unlike Python's standard tarfile module, exarch applies security validation by default.

Supported Formats

Format Extensions Extract Create List Verify
TAR .tar ✅ ✅ ✅ ✅
TAR+GZIP .tar.gz, .tgz ✅ ✅ ✅ ✅
TAR+BZIP2 .tar.bz2, .tbz2 ✅ ✅ ✅ ✅
TAR+XZ .tar.xz, .txz ✅ ✅ ✅ ✅
TAR+ZSTD .tar.zst, .tzst ✅ ✅ ✅ ✅
ZIP .zip ✅ ✅ ✅ ✅
ZIP-family .jar, .war, .ear, .nar, .nbm, .apk, .aab, .ipa, .appx, .msix, .whl, .vsix, .xpi, .epub ✅ — ✅ ✅
7z .7z ✅ — ✅ ✅

Note: ZIP-family formats share the ZIP container but add extra structure (signing, checksum manifests, ordering rules) that exarch doesn't produce, so creation is rejected for those extensions. 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons. A 7z archive holding a Windows reparse point is refused as a whole; a Unix S_IFLNK symlink is read and validated through the symlink policy, so it is created only with symlinks allowed, and a 7z FIFO, socket or device node is refused.

Comparison with tarfile

# UNSAFE - tarfile has known vulnerabilities (CVE-2007-4559)
import tarfile

with tarfile.open("archive.tar.gz") as tar:
    tar.extractall("/output")  # May extract outside target directory!

# SAFE - exarch validates all paths
import exarch

exarch.extract_archive("archive.tar.gz", "/output")  # Protected by default

Development

This package is built using PyO3 and maturin.

# Clone repository
git clone https://github.com/bug-ops/exarch
cd exarch/crates/exarch-python

# Build with maturin
pip install maturin
maturin develop

# Run tests
pytest tests/

License

Licensed under either of:

at your option.

Metadata

Release files for exarch 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for exarch 0.9.0
File Actions
exarch-0.9.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for exarch-0.9.0-cp39-abi3-win_amd64.whl
exarch-0.9.0-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for exarch-0.9.0-cp39-abi3-musllinux_1_2_x86_64.whl
exarch-0.9.0-cp39-abi3-musllinux_1_2_aarch64.whl CPython 3.9 abi3 Linux musl 1.2+ ARM64 Details for exarch-0.9.0-cp39-abi3-musllinux_1_2_aarch64.whl
exarch-0.9.0-cp39-abi3-manylinux_2_34_x86_64.whl CPython 3.9 abi3 Linux glibc 2.34+ x86-64 Details for exarch-0.9.0-cp39-abi3-manylinux_2_34_x86_64.whl
exarch-0.9.0-cp39-abi3-manylinux_2_34_aarch64.whl CPython 3.9 abi3 Linux glibc 2.34+ ARM64 Details for exarch-0.9.0-cp39-abi3-manylinux_2_34_aarch64.whl
exarch-0.9.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for exarch-0.9.0-cp39-abi3-macosx_11_0_arm64.whl
exarch-0.9.0-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for exarch-0.9.0-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 16.8 MB

Release files / exarch-0.9.0-cp39-abi3-win_amd64.whl

Download URL exarch-0.9.0-cp39-abi3-win_amd64.whl
Size 2.3 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
79b6430d9490538e13ba73d891b227a4b56acc7e4689f45431cab1723574abed
BLAKE2b-256 checksum
How to use checksums
9f58701bfca05b00c2be713e58f532939aaf728f3ca68936c371760453ddb045
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL exarch-0.9.0-cp39-abi3-musllinux_1_2_x86_64.whl
Size 2.7 MB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
dc1eddb87c37b95c1b935855096d8ed4aee05341fcfac42f0f4481a72b2d27c2
BLAKE2b-256 checksum
How to use checksums
6614b0625f49544333512c7f7fae79b6c41ed002ec68360ec349f0dd4d3ee5e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-musllinux_1_2_aarch64.whl

Download URL exarch-0.9.0-cp39-abi3-musllinux_1_2_aarch64.whl
Size 2.5 MB
Tags CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
6f91fc7571af74dd56312eeca5ce739775e7eb37b125146322c388c8b3ce2860
BLAKE2b-256 checksum
How to use checksums
ed951050aab880ea6c843cb48d07cab18e7ba792de7a3142931e461c4051248f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-manylinux_2_34_x86_64.whl

Download URL exarch-0.9.0-cp39-abi3-manylinux_2_34_x86_64.whl
Size 2.5 MB
Tags CPython 3.9 Linux glibc 2.34+ x86-64 abi3
SHA-256 checksum
How to use checksums
94fa05ba0dc02d29497d11ddd2e1cf245bd282fa014ff0fb956ba5ad3df0ce31
BLAKE2b-256 checksum
How to use checksums
6035dc43f3352695cfe4c93ca3500464a9401a19656d2d7fec7c0cbde2d60c33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-manylinux_2_34_aarch64.whl

Download URL exarch-0.9.0-cp39-abi3-manylinux_2_34_aarch64.whl
Size 2.3 MB
Tags CPython 3.9 Linux glibc 2.34+ ARM64 abi3
SHA-256 checksum
How to use checksums
09d2159a14c4dae11226c25ff35a104b23503b8a1400930505f47d3cba1804d1
BLAKE2b-256 checksum
How to use checksums
465d995c8cb7ab5231bf7c90fc3c17b153f8b845c50e4317b833191b014dfcbd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL exarch-0.9.0-cp39-abi3-macosx_11_0_arm64.whl
Size 2.1 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
15336cb3849665f26140e3f07df4574b7946eac066f7fbb6fa66ca6131f5e5ba
BLAKE2b-256 checksum
How to use checksums
a2fa66b2839123a3cb3338f386cc11d060a2c392237d0cf779f8a7674a290cc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / exarch-0.9.0-cp39-abi3-macosx_10_12_x86_64.whl

Download URL exarch-0.9.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 2.3 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
d0c4d82c0b71762c2b2214571dd05f1d033c8a3db1dbc604bd1f7db86af066d5
BLAKE2b-256 checksum
How to use checksums
a780ca9f1cd1648bcbbe0fb6b15d6caa219b20ca748d12303ad7b1b86f4223ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for exarch 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for exarch-0.9.0-cp39-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page