CompressMe

A powerful, cross-platform image compression tool — modern PySide6 GUI + full CLI.

Batch-compress thousands of images, detect duplicates, preserve metadata, and generate detailed reports — all in one place.

Preview · Platforms · Features · Quick Start · CLI · Build · License

---

Preview

Dashboard	Import & Drag & Drop
Compression	Compression Finished
Reports & History	About

---

Supported Operating Systems

Windows	Linux	macOS	Android
Supported	Supported	Coming soon	Coming soon

---

Features

• Batch Compression — Compress thousands of images in one go with parallel processing
• Dual Interface — Desktop GUI (PySide6) and CLI for scripting/automation
• Format Support — JPEG, PNG, WebP, AVIF, GIF, plus RAW (CR2, NEF, ARW, DNG, etc.)
• Duplicate Detection — SHA-256 exact hash + perceptual hash (pHash) to find near-duplicates
• Metadata Preservation — EXIF orientation, ICC profiles, file timestamps
• External Tool Detection — Auto-detects pngquant, oxipng, cwebp, jpegoptim, avifenc for better compression
• Detailed Reports — CSV, JSON, TXT reports with compression ratios, savings, and failed files
• Automatic Update Check — Checks GitHub for new releases on launch and notifies you in-app (no auto-install)
• Dark/Light Theme — Eye-candy Qt stylesheets with auto-persistence
• Drag & Drop — Drag folders onto the GUI to start compressing immediately

---

Quick Start

Prerequisites

• Python 3.10+
• pip

Installation

git clone https://github.com/johnvexcoder/CompressMe.git
cd CompressMe
pip install -r requirements.txt

Run the GUI

python main.py

Run the CLI

python compressme.py --dir ./my-photos --quality 80 --format webp --dedupe hash

---

GUI Pages

Page	Description
Dashboard	At-a-glance stats: images, duplicates, space saved
Compress	Drag-drop folder, adjust quality/format, start/stop
Settings	Theme, accent, default quality, workers, metadata options
Updates	Check for new releases, auto-update toggle, version info
History	Past compression sessions loaded from saved reports
Reports	Load & browse CSV/JSON report files
About	Version, author, GitHub link

---

CLI Usage

compressme.py [-h] --dir DIRECTORY [--quality QUALITY] [--format FORMAT]
              [--dedupe {hash,perceptual,none}] [--dry-run]
              [--benchmark] [--workers WORKERS]

Argument	Default	Description
--dir	(required)	Directory to scan for images
--quality	85	Output image quality (1–100)
--format	keep	Output format: keep, jpeg, png, webp, avif
--dedupe	hash	Duplicate detection: hash, perceptual, none
--dry-run	false	Scan & report without compressing
--benchmark	false	Run compression benchmark
--workers	auto	Number of parallel workers

---

Building From Source

Windows — Standalone EXE

pip install -r requirements.txt
pyinstaller CompressMe.spec --clean --noconfirm

The executable is produced at dist/CompressMe.exe. Windows version metadata lives in version_info.txt.

The GitHub Actions workflow also builds the EXE automatically on every push and uploads it as an artifact.

Linux — AppImage

pip install -r requirements.txt
pyinstaller CompressMe-linux.spec --clean --noconfirm --distpath dist/linux

The result is a one-dir bundle at dist/linux/CompressMe/. To package it into an AppImage:

# Assemble an AppDir (bundle + .desktop file + AppRun + icons), then:
appimagetool AppDir            # -> CompressMe-<version>-x86_64.AppImage

---

Project Structure

CompressMe/
├── main.py                  # GUI entry point
├── compressme.py            # CLI entry point
├── src/
│   ├── backend/             # Compression engine (shared by GUI & CLI)
│   │   ├── engine.py        #   Core compression logic
│   │   ├── hashing.py       #   SHA-256 & perceptual hashing
│   │   ├── reporter.py      #   CSV/JSON/TXT reports
│   │   ├── utils.py         #   Helpers (EXIF, format, timestamps)
│   │   └── constants.py     #   File extensions, modes
│   ├── gui/                 # PySide6 desktop interface
│   │   ├── main_window.py   #   Main window + sidebar navigation
│   │   ├── compress_page.py #   Compression page
│   │   ├── dashboard_page.py#   Statistics dashboard
│   │   ├── settings_page.py #   Settings (incl. Updates)
│   │   ├── history_page.py  #   Session history
│   │   ├── reports_page.py  #   Report viewer
│   │   ├── about_page.py    #   About page
│   │   ├── theme.py         #   Dark/Light stylesheets
│   │   ├── icons.py         #   Vector icon factory
│   │   ├── widgets.py       #   Reusable components
│   │   └── worker.py        #   Background compression thread
│   ├── updater/             # GitHub release check + update notifications
│   ├── config/              # App configuration
│   │   ├── settings.py      #   JSON config loader/saver
│   │   └── version.py       #   Single source of truth for APP_VERSION
│   └── ...
├── img/                     # Screenshots & OS badges (README)
├── .github/workflows/       # GitHub Actions — Windows EXE build
├── requirements.txt         # Python dependencies
├── CompressMe.spec          # PyInstaller config (Windows one-file)
├── CompressMe-linux.spec    # PyInstaller config (Linux one-dir)
└── version_info.txt         # Windows version metadata

---

Dependencies

Package	Required	Purpose
Pillow	Yes	Core image processing
PySide6	Yes	Desktop GUI framework
numpy	Yes	Array operations
pillow-heif	No	HEIF/HEIC support
pillow-avif-plugin	No	AVIF support
rawpy	No	RAW camera formats
imagehash	No	Perceptual duplicate detection
piexif	No	EXIF metadata handling
python-magic	No	MIME type detection
tqdm	No	CLI progress bars
rich	No	CLI formatted output

---

License

MIT License — see LICENSE.

---

Author

J0hn Vex Coder
github.com/johnvexcoder