Skip to main content

Installation

Python 3.9+ on macOS, Linux, or Windows.

Using pip​

pip install filerepack

Using uv or pipx​

uv tool install filerepack
# or
pipx install filerepack

From source​

git clone https://github.com/ivbeg/filerepack.git
cd filerepack
pip install -e ".[dev]"

Source releases include test fixtures/helpers and pytest configuration; runtime wheels include the application package. Builds require setuptools 77.0.3+ for BSD-3-Clause SPDX metadata; PEP 517 installs it in an isolated build environment. For development/release checks, the dev extra also includes build:

python dev/validate_distribution.py

This builds and installs both artifacts in temporary virtual environments and checks the extracted tests against the installed runtime, CLI and license metadata. Optional integrations remain explicit test skips when their dependencies are absent.

Optional extras​

Some formats need extra Python packages. This is the canonical list; feature sections elsewhere in the docs link back here.

ExtraEnables
parquetPyArrow 19+ Parquet recompress with preservation checks
dataParquet plus ORC / Avro / Feather / Arrow
fontsWOFF / WOFF2 via fonttools
progressrich progress bars for repack and bulk --progress
mediamutagen cover-art walking in MP3 / FLAC / M4A / Ogg / APE
pdfpikepdf image walking plus Pillow image decoding; lossless comparison needs qpdf 11+
validationPillow raster verification and pikepdf protection-inspection fallback
oleolefile 0.47 for legacy DOC/XLS/PPT compaction; also requires the separately built native writer
ole-recompressolefile and psutil for opt-in OLE EMF/WMF and PPT embedded-object recompression; Zopfli 0.4.3 on Python 3.10+, zlib on Python 3.9; native writer 0.4.0+
serializationPassive RDS/RDA/RData, PT/PTH checkpoint and SAV/experimental ZSAV handlers with worker isolation
scientificNumPy, h5py, netCDF4, tifffile and imagecodecs for preserving HDF5/NetCDF/TIFF and experimental MAT profiles; HDF5 also needs h5repack
zarrZarr 2.18–2.x, NumPy and compatible numcodecs for complete offline local v2 stores via repack-store
onnxBounded ONNX inspection and checker; no recompression writer
tracev3LZ4 and worker isolation for archived Apple Unified Log chunk streams
dicompydicom, NumPy and pyjpegls for DICOM parsing and decoded-pixel verification
fitsAstropy/CFITSIO lossless FITS tiled-image compression and verification
blendZstandard compression/decompression for Blender projects; gzip uses the standard library
duckdbDuckDB 1.4.2+ and PyArrow 19+ for verified offline database compaction
tgsZopfli for stronger Telegram TGS compression; standard-library gzip is the fallback
devBuild, pytest/coverage, lint/type checks and selected integration readers for repository development
pip install 'filerepack[parquet]'
pip install 'filerepack[data]'
pip install 'filerepack[fonts]'
pip install 'filerepack[progress]'
pip install 'filerepack[media]'
pip install 'filerepack[pdf]'
pip install 'filerepack[validation]'
pip install 'filerepack[ole]'
pip install 'filerepack[ole-recompress]'
pip install 'filerepack[serialization]'
pip install 'filerepack[scientific]'
pip install 'filerepack[zarr]'
pip install 'filerepack[onnx]'
pip install 'filerepack[tracev3]'
pip install 'filerepack[dicom]'
pip install 'filerepack[fits]'
pip install 'filerepack[blend]'
pip install 'filerepack[duckdb]'
pip install 'filerepack[tgs]'

Extras can be combined, for example pip install 'filerepack[data,pdf,validation]'. With uv or pipx, install the extras into the tool's own environment: uv tool install 'filerepack[data,pdf,validation]' or pipx install 'filerepack[data,pdf,validation]'. Installing them with a separate system pip does not add them to an isolated tool environment.

External tools​

Install filerepack[scientific] for HDF5/NetCDF readers and native writers. HDF5 also requires h5repack; NetCDF uses the Python netCDF4 writer and does not require nccopy. Unsupported or missing decoders leave candidates unpublished.

Most formats also need command-line binaries (7zz, jpegoptim, qpdf, ffmpeg, …). 7zz or 7z is required for ZIP/OOXML and generic archive work; native CPIO and WARC do not require it. doctor still exits 1 when the archiver is missing. Other tools enable their corresponding formats.

See what you have and how to install the rest on this OS:

filerepack doctor

Install commands use Homebrew or MacPorts on macOS, apt / dnf / pacman / zypper / apk on Linux, and Chocolatey / winget / Scoop on Windows. mp3packer and optivorbis are not packaged; doctor points at GitHub CLI zips.

Full notes: External tools. Override paths with FILEREPACK_7ZZ (and similar) or ~/.config/filerepack/config.toml.

Next steps​