magicdispel 0.2.0

Remove private metadata from photos and videos on your own computer, without changing a single pixel.

A photo carries more than its pixels: where it was taken, when, on which phone, and sometimes hidden extras such as depth maps, portrait mattes and even the serial number of your display. A video may carry a GPS track of every second and its camera's serial number. MagicDispel saves a clean copy with none of that, and nothing a viewer sees or hears is changed.

Quick start

macOS and Linux:

curl -LsSf https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.ps1 | iex"

Then type magicdispel and a space, drag photos or videos into the terminal, and press Enter. A cleaned copy appears next to each original.

Why MagicDispel

• It rebuilds instead of deleting. Most tools delete the metadata they know about. MagicDispel writes a new file from only the parts needed to show the image, so metadata it has never heard of is left behind too. The parts it keeps must match their exact layout, so nothing can ride along inside them.
• Every pixel stays. Compressed image data is copied byte for byte, never recompressed. Color profiles, orientation, DPI, transparency, animation and HDR gain maps are kept, so a photo looks exactly the same, in HDR too. A video keeps every frame and every sound sample as they were, with its rotation, HDR, Dolby Vision and spatial video information.
• It finds what others miss. Depth maps and portrait mattes inside iPhone photos, thumbnails and previews that may show the uncropped original, C2PA manifests, data hidden after the end of the image, the dates and times in file names, the display model and serial number in screenshots' color profiles, and the GPS tracks, face data and camera serial numbers inside videos.
• It checks before it saves. Every result is read back on its own and compared with the original, frame by frame. ExifTool, if installed, gives an independent second opinion. If anything is off, nothing is saved.
• It stays on your computer. No uploads, telemetry or network access. Originals are never modified, and existing files are never overwritten.

Compared with the usual one-liner

Many guides suggest exiftool -all=. ExifTool is an excellent metadata editor, and with extra options it can keep color data, but the one-liner and MagicDispel give very different results. Tested on real photos with ExifTool 13.55 on macOS:

"Looks identical" means identical renders in macOS ImageIO and ColorSync: pixels, sRGB, Display P3, HDR, gain maps, orientation and DPI.

For videos, guides suggest exiftool -all= or ffmpeg -map_metadata -1 -c copy. Tested on public sample videos with ExifTool 13.55 and FFmpeg 8.1 on macOS:

"Plays identically" means that FFmpeg decodes identical frames, and that macOS AVFoundation sees the same video and sound tracks and shows the same frames.

How it works

1. Identify the format from the file's contents, not its name.
2. Rebuild a new file from an allowlist: the image data and the few fields needed to show it, such as color, orientation and HDR, some of them written afresh. Everything else is left behind.
3. Verify the result. It must parse on its own, decode to identical frames (for HEIC and videos, every image item and sample is compared byte for byte), and satisfy ExifTool when it is installed. The original must not have changed in the meantime.
4. Save the copy next to the original under a new name, without ever overwriting a file.

Files that cannot be rebuilt safely, such as damaged files, RAW photos or unknown structures, are refused with an explanation instead of being passed through. Privacy and format details describe every check.

What is kept and removed

ICC profiles keep their color data. Their date becomes a fixed placeholder (2000-01-01), their description Clean, and device and creator fields are cleared. Images up to 268 megapixels are checked, enough for 200-megapixel phone photos; larger ones are refused. Videos are cleaned in a copy next to the original without being read into memory: a 4.7 GB video takes about five seconds on a Mac. Fragmented and encrypted videos, videos with subtitles, Google's 360-degree videos, and codecs MagicDispel does not know are refused. Apple's 180- and 360-degree videos keep their projection.

File names

A cleaned copy is named after its original with _clean added, but without the dates, times and timestamps that screenshots, phone cameras and chat apps put in names:

Further copies get _clean_1, _clean_2... --keep-name keeps the original name as it is, and --anonymous uses a random name such as photo_3f9c...e1.jpg or video_3f9c...e1.mov instead.

Usage

magicdispel photo.jpg "Screenshot 2026-09-23 at 15.14.15.png" portrait.heic IMG_1234.MOV
magicdispel --anonymous photo.jpg
magicdispel --check

Quote paths containing spaces, or drag the files into the terminal. Folders are not processed recursively. A file whose name starts with - goes after --: magicdispel -- -photo.jpg. Exit codes: 0 success or help, 1 one or more files not cleaned, 2 invalid arguments, 130 interrupted. A failed file never stops the rest of a batch.

More ways to install

With uv or pipx and Python 3.10 or newer:

uv tool install magicdispel
pipx install magicdispel

The one-line installers are short scripts you can read first: install.sh and install.ps1. They install uv if needed, which brings its own Python when the system has none that fits. If magicdispel is not found afterwards, open a new terminal window.

To update, run the installer again or uv tool upgrade magicdispel. To remove MagicDispel, run uv tool uninstall magicdispel.

ExifTool is optional. When version 12.73 or newer is installed, MagicDispel uses it to double-check every result: brew install exiftool, sudo apt install libimage-exiftool-perl or winget install --exact --id OliverBetz.ExifTool. If it is installed somewhere unusual, set MAGICDISPEL_EXIFTOOL to its full path.

Questions

Does it change my original photo or video? No. MagicDispel only reads the original. The clean copy is a new file next to it, and no existing file is ever overwritten.

Does anything leave my computer? No. MagicDispel never uses the network. Only the installer downloads uv and MagicDispel itself.

Why is a cleaned HEIC or video about as large as the original? HEIC files and videos are cleaned in place, so every offset inside them stays valid: removed data is overwritten with zeros rather than cut out. It is gone, but its space remains.

Why was my file refused? When a file cannot be rebuilt safely, MagicDispel says why and saves nothing rather than guess. The file may be damaged, use a structure MagicDispel does not know, or be a RAW photo: export RAW photos as JPEG or HEIC first.

Can I still edit portrait effects afterwards? No. Depth maps and portrait mattes are removed, so Photos can no longer change the portrait blur or lighting of the copy. Likewise, a cleaned video loses the data only its maker's app reads, such as the Live Photo data that pairs a video with its photo in Photos, or Samsung's slow-motion sections, so those apps may no longer offer such effects. Keep the original if you may want to edit it later.

Does it make me anonymous? No. What the picture shows can still identify people and places: faces, signs, reflections, the view from a window. So can a match with a copy published before, or the account it is shared from. MagicDispel removes metadata; it does not change the picture.

How do I report a problem? Open an issue and fill in the form, without attaching private photos. If a file keeps private data after cleaning, report it privately instead, as SECURITY.md explains.

Development

python -m venv .venv
# Activate the environment for your shell.
python -m pip install -e ".[test]" build
python -m unittest discover -s tests -v
python -m build

The tests need only Pillow. When ExifTool is installed, they also add metadata the way other programs write it and let ExifTool double-check each result. No personal photos or videos are included.

Before and after any change to the cleaning code, run the regression harness over a folder of real sample photos and videos kept outside the repository:

python scripts/make_probes.py ~/magicdispel-corpus    # adds synthetic leak probes
python scripts/regression.py ~/magicdispel-corpus     # saves a run under runs/
python scripts/regression.py ~/magicdispel-corpus --baseline ~/magicdispel-corpus/runs/<run>.json

It checks that every output looks identical to its input (Pillow, and macOS ImageIO/ColorSync when available; for videos, FFmpeg and macOS AVFoundation), that no probe marker survives, and, against a baseline, that no sample changes outcome or gains metadata. Pure refactors should also pass --identical, and --without-exiftool checks the path users without ExifTool take.

.github/workflows/test.yml runs the tests on macOS, Windows and Linux with Python 3.10 and 3.13, with and without ExifTool, and the install scripts on all three. release.yml publishes a tagged version to PyPI once those pass. scripts/screenshot.py renders the images in this README.

License and attribution

MagicDispel is designed by VincentC and MIT licensed. ExifTool, an optional companion, is developed by Phil Harvey and distributed separately under its own license. MagicDispel is not affiliated with ExifTool.