A Practical Walkthrough for S H A G M AG
S H A G M A G is a batch image processing utility that sits somewhere between a script runner and a full-blown editor. It's not for casual users. The interface is terminal-heavy and the documentation reads like it was written by someone who assumes you already know what's happening. That said, if you're moving more than fifty images at once and need consistent output, it saves a ton of manual effort. The standard workflow starts with defining a pipeline. You create a config file that lists your input directory, output directory, and the sequence of operations you want run in order. The supported operations include cropping, color space conversion, sharpening, metadata stripping, and resolution scaling. Each operation takes parameters. The tricky part isn't running it once — it's getting the parameter values right before you commit to a full batch.
Getting Started with S H A G M A G
Download it from the official repository. The latest stable build at the time of writing is 3.2.1. Clone the repo or grab the release tarball, then install the dependencies. Python 3.9 or later. Pillow, OpenCV, and exiftool need to be present on your system. On Ubuntu or Debian, a single apt install command handles most of it. On macOS you'll need Homebrew. Windows users — use WSL2. The native Windows build exists but has known issues with path handling on network drives. Once installed, verify the setup by running the included test suite: shagmag --test. If it passes, you're good to go. If it fails, check your OpenCV version. Version mismatches are the most common failure point and it usually means you have two installations fighting each other. Create a basic config file to get comfortable. Something like this:
[general] input_dir = /path/to/source output_dir = /path/to/output log_level = info [operations] resize = width=1200,height=800,method=lanczos sharpen = strength=0.4 strip_metadata = true Run it with: shagmag --config pipeline.conf --dry-run. The dry-run flag is critical. It tells you exactly what would happen without touching a single file. Skip it at your own risk. I learned that the hard way.
What Nobody Tells You About S H A G M A G
The first thing I ran into wasn't documented anywhere useful: S H A G M A G processes files in filesystem traversal order by default, not in alphabetical or chronological order. That sounds minor until you realize that if your input directory is served over NFS or mounted via SMB, the traversal order becomes unpredictable. Files that look like they should process sequentially will get jumbled. The fix is to add sort_keys = name_asc to your config. It adds roughly 0.3 seconds of overhead per thousand files but eliminates random sorting bugs that can take hours to diagnose. Another counter-intuitive behavior: the sharpening operation doesn't operate on the same data you think it does. When combined with a resize operation, S H A G M A G applies sharpening to the pre-resized image, not the final output. This means your sharpening kernel is effectively too aggressive because it's being applied to a larger image before the reduction happens. The workaround is to reverse the operation order in your config — put sharpening after resize. The documentation mentions this once in a footnote. I wish more people had seen it before ruining three hundred RAW files trying to figure out why everything looked oversharpened. Memory usage is another hidden problem. S H A G M A G loads entire images into RAM before processing. A batch of four-megapixel JPEGs is fine. A batch of fifty-megapixel camera RAW files from a Phase One or Hasselblad will exhaust available memory quickly, especially if you're using multithreading. The default thread count is eight. Drop it to four for large files. The trade-off is processing speed, but crashing mid-batch is worse than going slower.
Edge Cases That Will Waste Your Weekend
I encountered a problem last month where S H A G M A G silently dropped the alpha channel on PNG inputs. The output files looked correct at first glance because the background was white. But any image with actual transparency — icons, logos, UI assets — came out with transparent areas filled in. This only affects PNG and WebP input with preserve_transparency = false, which is the default. Set it to true. It's not obvious from the config schema comments. Color profile embedding is another minefield. S H A G M A G will convert to sRGB by default during output if you specify color_space = srgb. But if your source images contain embedded ICC profiles and you don't set preserve_profile = true, the conversion happens without any soft-proofing step. The result looks flat and slightly wrong on calibrated displays. I wasted an afternoon chasing what I thought was a monitor calibration issue before realizing the tool was eating my color profiles. There's also a bug in version 3.2.0 and 3.2.1 where EXIF GPS data causes a crash when you enable metadata stripping. It's been patched in the development branch but isn't in the stable release yet. If you're working with location-tagged photos, either downgrade to 3.1.4 or apply the manual patch from the GitHub issues page. The workaround is to strip GPS manually before running the batch, using exiftool directly: exiftool -gps*= input_dir/.
When S H A G M A G Isn't the Right Tool
It's worth being honest about the limitations. S H A G M A G is not good at selective processing. If you need to apply different operations to different subsets of your images based on filename patterns, camera model, or EXIF criteria, you're better off writing a custom script or using ImageMagick with more granular control. S H A G M A G treats every file in the input directory the same way unless you explicitly configure conditionals, and the conditional syntax is awkward even when it works. It also has no built-in error recovery. If a single file crashes mid-batch, the entire process stops. There's no resume flag. You'll need to manually track which files were processed and rebuild your input list for the next run. This is especially painful on large batches over slow networks where a single corrupted file can halt everything for hours. If you need batch processing with resilience and selective logic, consider fast-picture-resize or building a Python wrapper around PIL that logs progress and skips failed files. For simple, uniform, no-frictions batches, S H A G M A G is efficient and fast. The sweet spot is roughly fifty to five hundred files per run, uniform source types, and no complex conditional logic required.
Final Notes on Getting Results
Always run a dry-run first. Always set log_level = debug when something goes wrong — the default info level hides the details you actually need. Keep your config files in version control. The tool doesn't store history of what you've run, so if you make a change and lose track of it, you'll end up running inconsistent batches against the same source directory. That happened to me once. Recovering from it took two days of reorganizing output folders and cross-referencing timestamps. The installation is straightforward. The gotchas are subtle. Read the source code if you can — it's about twelve thousand lines and well-commented. The authors have clearly put work into making the internals readable. Understanding what happens under the hood will save you far more time than reading the docs will.
