Metadata Cleaner is a privacy-focused local tool for viewing and removing metadata from images, documents, audio, and video files. It writes cleaned copies by default, keeps originals unchanged, and includes CLI, JSON automation, Docker, and a local Web UI for side-by-side metadata checks.
- View metadata before cleaning.
- Remove metadata into separate cleaned copies.
- Compare original and cleaned metadata in a local-only Web UI.
- Process individual files or recursive folders.
- Generate machine-readable JSON reports for automation.
- Add SHA-256, SHA-512, or BLAKE2b checksums to reports.
- Preserve source timestamps on cleaned outputs when needed.
- Publish-ready CI coverage for Python, package smoke tests, Docker builds, CodeQL, and dependency audits.
- 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
Some formats need system tools for best coverage:
ffmpegandffprobeare required for video metadata handling.exiftoolis required for AVIF, HEIC, and HEIF cleanup and improves image metadata coverage.- The published Docker image includes these optional tools.
Requires Python 3.11 or newer.
pip install metadata-cleaner
metadata-cleaner --helpUse Docker when you want the optional system tools preinstalled:
docker run --rm -v "$(pwd):/data" ghcr.io/sandy-sp/metadata-cleaner:latest delete /data/photosFor development:
git clone https://github.com/sandy-sp/metadata-cleaner.git
cd metadata-cleaner
poetry install --with dev
poetry run metadata-cleaner --helpView metadata:
metadata-cleaner view sample.jpgClean one file:
metadata-cleaner delete sample.jpgBy default, the cleaned copy is written under a cleaned/ directory next to the
source file. To choose the output path:
metadata-cleaner delete sample.jpg --output cleaned/sample.jpgPreview a folder run without writing files:
metadata-cleaner delete ./photos --dry-runClean a folder recursively:
metadata-cleaner delete ./photos --output ./cleaned-photosStart a single-page local Web UI:
metadata-cleaner webThe Web UI binds to 127.0.0.1 by default, shows original metadata beside
cleaned-copy metadata, and lets you download cleaned files. The Files button
lists uploaded originals and cleaned copies from the current local session with
view and delete actions.
Temporary Web UI files are stored in a temporary directory unless you provide a workspace:
metadata-cleaner web --workspace ./metadata-cleaner-workspacePrint metadata as JSON:
metadata-cleaner view sample.jpg --jsonWrite metadata JSON to a file:
metadata-cleaner view sample.jpg --json-output reports/metadata.jsonWrite a delete summary report:
metadata-cleaner delete ./photos --summary-file reports/summary.jsonThe shared --json-output reports/summary.json option writes the same delete
summary payload.
Add checksums:
metadata-cleaner delete ./photos --summary-file reports/summary.json --checksums
metadata-cleaner delete ./photos --json-summary --checksums --checksum-algorithm sha512Use compact reports for large jobs:
metadata-cleaner delete ./photos --json-summary --report-detail compact
metadata-cleaner delete ./photos --json-summary --report-filter failedSummary reports include per-file status, output paths, optional checksums, failure reasons, and format-specific processing notes that explain whether a handler copies, rewrites, re-saves, uses ExifTool, deletes audio tags, or remuxes video with FFmpeg stream copy.
- Originals are not modified by metadata removal.
- Handlers reject in-place cleanup where input and output paths are the same.
- EPUB and ODT ZIP packages are checked against archive safety limits before metadata XML is read or rewritten.
- ExifTool, FFmpeg, and FFprobe subprocess calls use bounded timeouts.
- Logs go to stderr by default; file logging is opt-in.
- The Web UI is local-only by default and scopes file viewing/deletion to its managed workspace.
This tool removes common metadata fields using format-specific libraries and system tools. It is not a guarantee that every possible identifying byte, watermark, hidden payload, or content-derived signal has been removed. For high-risk publishing workflows, inspect outputs with independent tools before release.
Editing is available only where handlers support it, currently most useful for audio files through Mutagen:
metadata-cleaner edit song.mp3 --changes '{"artist": "Unknown"}'Use metadata removal when you need a cleaned copy. Editing may modify the target file in place.
python3 manage.py test
python3 manage.py lint
python3 manage.py checkCI runs tests, lint, pip-audit, package smoke coverage, Docker builds, and
CodeQL on protected branches and pull requests.