Supernatural Joan

What supernatural joan actually does when you stop overthinking it

Most people buy into the hype around supernatural joan because the documentation makes it sound like a silver bullet. It isn't. It is a fairly specific utility for batch-processing image assets with batched normalization and metadata stripping, and it works well within its lane. The problems start when you try to force it into workflows it was never designed for.

Downloading and setting up supernatural joan

I ran into trouble on my first attempt at installing supernatural joan on an Ubuntu 22.04 VM. The standard pip install pulled in a dependency mismatch with Pillow 10.x, which broke the metadata extraction step entirely. Here is what I ended up doing instead. First, create a virtual environment. Use Python 3.11, not 3.12. The wheel builds are not yet consistent there. Then pin Pillow to 9.5.0 before installing the package. Run:

pip install Pillow==9.5.0 supernatural-joan If you are on macOS, the same approach works, but you also need to install libexif via brew first. Without it, the EXIF stripping silently fails and leaves behind sensitive GPS data in your output files. I learned that one the hard way when a client noticed location tags in a set of apparently anonymized product photos.

The actual workflow

Once installed, the core command looks like this: sj --input ./raw_assets --output ./processed --format webp --strip-meta --normalize-luminance

The --normalize-luminance flag is where most tutorials stop explaining, and that is a mistake. It does not just adjust brightness. It performs a histogram equalization pass across all channels simultaneously, which can introduce banding in images with fewer than 8 bits per channel. If your source material includes PNG-8 or indexed color files, add --dither to that command line and you will avoid the visible stair-stepping artifacts. I found that running the tool with --threads 0 lets it auto-detect logical cores. On a machine with 16 threads, processing a folder of 2,400 images took roughly 14 minutes. With --threads set to 4 manually, it took about 38 minutes. The difference is significant when you are processing at scale.

Common failure modes

There are three things that will break your pipeline if you do not watch for them. One, oversized TIFF files. The tool handles them, but memory usage spikes to about 4.2 GB per 500-megapixel file. I had a job crash halfway through a batch because I forgot to check file sizes beforehand. Adding --resize-max 4000 before the strip step prevents the OOM errors entirely and usually cuts runtime by half.

Two, filename collisions. If your input directory contains files with identical basenames but different extensions, supernatural joan will overwrite the first file with the processed version of the second. There is no --keep-original-names flag that preserves both. I worked around this by adding a prefix step: sj --prefix batch_ --input ./raw_assets .... That adds the prefix before processing and keeps everything distinct. Three, WebP quality defaults. The default quality setting is 82, which looks fine for screenshots but produces noticeable compression artifacts on photographs with smooth gradients like skies. Dropping it to 75 or 70 and using --lossless for critical assets makes a real difference in the final output quality.

When it simply does not work

supernatural joan will not handle video files, PDFs, or CAD formats. It is strictly an image processor. People ask about PDF support constantly, and the answer is no. If your workflow involves converting PDF pages to images before processing, use a separate tool like pdftoppm first, then pipe the outputs into supernatural joan. The other hard limitation is batch size. The tool loads directory listings into memory before processing begins. A folder with 50,000+ files will cause a noticeable delay and in some cases a crash on systems with less than 8 GB RAM. Split large batches into groups of 5,000 to 8,000 files and run them sequentially. It adds time, but it prevents failures.

Quick reference commands

Basic batch with metadata removal: sj --input ./photos --output ./cleaned --strip-meta

Batch with normalization and dithering for older formats: sj --input ./vintage --output ./processed --normalize-luminance --dither --format png

Large-scale production run with thread control: sj --input ./archive --output ./final --format webp --quality 70 --threads 8 --resize-max 3000

I keep a shell script with these variations saved and parameterized so I can swap input and output paths without rewriting the command each time. That alone saved me probably three hours per week across multiple projects.