Zotero PDF Compressor

Python utility for shrinking the PDF attachments in your Zotero library (or any folder of PDFs). The compress_pdfs.py script walks subfolders recursively, uses PyPDF to lower image quality, applies lossless Flate compression on each page, and saves the PDFs in place while reporting total space savings.

Installation

The project targets Python 3.10+. Install the Python dependencies with one of the options below.

Using Conda

conda create -n zotero-compressor python=3.11
conda activate zotero-compressor
pip install -r requirements.txt

Using venv (built-in virtual environments)

python -m venv .venv
.\.venv\Scripts\activate        # PowerShell on Windows
# source .venv/bin/activate     # macOS / Linux
pip install -r requirements.txt

Usage

python compress_pdfs.py <compression_ratio> [--folder PATH] [--lossless-level N]

• compression_ratio: Float between 0 and 1. Smaller values apply stronger compression by lowering embedded image quality more aggressively. Use a value like 0.6 for balanced compression or 0.3 for leaner files.
• --folder: Root directory that contains the PDFs you want to compress. When omitted, a system file dialog opens so you can pick the folder interactively.
• --lossless-level: Optional override (1–9) for the Flate compression level used when calling page.compress_content_streams. Leave unset to derive it automatically from the compression ratio.

Example

python compress_pdfs.py 0.6 --folder "D:\Zotero\storage"

The script prints step-by-step progress per PDF plus a summary of the total size before and after compression. Consider backing up your PDFs before running an aggressive compression ratio.

ℹ️ After running the script, the sizes of the pdf files should be updated on the Zotero Cache. To do that, open in Zotero Edit > Settings > Sync, click "Show Reset Options", select "Replace Online Library" and click Reset. Then, right click on your library name on the sidebar of main Zotero screen, and click Sync. This operation will resync your file sizes with te cloud