metadata-cleaner 3.18.0

A CLI tool to remove, edit, or selectively filter metadata from images, documents, audio, and video files.

Metadata Cleaner

Metadata Cleaner is a privacy-focused CLI for viewing and removing metadata from local files. It writes cleaned copies by default and avoids modifying originals in-place.

Supported Files

• Images: JPG, JPEG, PNG, TIFF, WEBP, AVIF, HEIC, HEIF
• Documents: PDF, DOCX, EPUB, ODT, TXT
• Audio: MP3, WAV, FLAC, OGG, AAC, M4A, WMA
• Video: MP4, MKV, MOV, AVI, WEBM, FLV

Video support requires ffmpeg and ffprobe. AVIF and broader metadata coverage benefit from exiftool.

Installation

Requires Python 3.11 or newer.

pip install metadata-cleaner
metadata-cleaner --help

For development:

git clone https://github.com/sandy-sp/metadata-cleaner.git
cd metadata-cleaner
poetry install --with dev
poetry run metadata-cleaner --help

CLI Usage

View metadata:

metadata-cleaner view sample.jpg

Print metadata for automation:

metadata-cleaner view sample.jpg --json

Remove metadata from one file:

metadata-cleaner delete sample.jpg

Write to a specific file:

metadata-cleaner delete sample.jpg --output cleaned/sample.jpg

Process a folder recursively:

metadata-cleaner delete ./photos --output ./cleaned-photos

Preview a run without writing files:

metadata-cleaner delete ./photos --dry-run

Write a JSON summary report:

metadata-cleaner delete ./photos --summary-file reports/summary.json

Summary reports include per-file status and output paths for audit trails. Add --checksums to include input/output hashes. SHA-256 is the default; use --checksum-algorithm sha512 or --checksum-algorithm blake2b for stronger hash reports. Add --preserve-timestamps when cleaned files should keep source file times. Use --report-detail compact or --report-detail summary for smaller reports. Use --report-filter failed to list only failed per-file entries. Formats that rewrite, re-save, or remux data include per-file warnings in JSON summary reports.

Edit metadata where supported:

metadata-cleaner edit song.mp3 --changes '{"artist": "Unknown"}'

Start the local Web UI:

metadata-cleaner web

The Web UI runs on 127.0.0.1 by default and shows original metadata next to cleaned-copy metadata so you can verify what changed before using the cleaned file.

Development Checks

python3 manage.py test
python3 manage.py lint
python3 manage.py check

CI runs tests, lint, and pip-audit on pull requests and pushes to main.

Docker

docker build -t metadata-cleaner .
docker run --rm -v "$(pwd)/photos:/data" metadata-cleaner delete /data

Published release images are available from GitHub Container Registry:

docker run --rm -v "$(pwd)/photos:/data" ghcr.io/sandy-sp/metadata-cleaner:latest delete /data

Logging

By default, logs go to stderr only. To write a log file, opt in explicitly:

METADATA_CLEANER_LOG_FILE=./metadata-cleaner.log metadata-cleaner delete sample.jpg

Use debug logging when needed:

METADATA_CLEANER_LOG_LEVEL=DEBUG metadata-cleaner view sample.jpg

Resources

• API Reference
• Usage Guide
• Architecture