Turn ugly screenshots into polished doc-ready images in one command.
What CleanShot X / Shottr / Pika charge for, in a single Python script you can drop into a CI pipeline.
prettyshot auto-crops empty margins, adds padding, applies a solid colour or gradient background, paints a soft drop shadow, rounds corners, and can wrap the whole thing in a fake browser window or a macOS-style window. Works on a single file or a whole folder.
Requires: Python 3.8+ and Pillow.
git clone https://github.com/nord342/prettyshot.git
cd prettyshot
pip install Pillow
chmod +x prettyshot.py
# optional: symlink onto your PATH
ln -s "$(pwd)/prettyshot.py" /usr/local/bin/prettyshot# zero-config: auto-crop, padding, soft shadow
prettyshot screenshot.png
# gradient background + bigger shadow
prettyshot screenshot.png --gradient sunset --shadow 40
# wrap in fake browser window with custom background
prettyshot screenshot.png --browser --bg "#1e1e2e"
# macOS-style window
prettyshot screenshot.png --macos --round 12
# batch: process every image in a folder
prettyshot ./screenshots/ --gradient ocean --padding 80
# CI-friendly: overwrite originals, keep backups
prettyshot ./docs/img/ --inplace --backup --gradient slateThe output goes next to the input with a _pretty suffix by default (e.g. hero.png → hero_pretty.png).
| Name | Colors |
|---|---|
sunset |
warm orange/peach |
ocean |
blue/cyan |
mint |
green |
purple |
purple → red |
slate |
dark grey |
blush |
soft pink |
forest |
deep green |
coffee |
brown/tan |
| Flag | Default | What it does |
|---|---|---|
--bg COLOR |
— | Solid background (hex "#1e1e2e", name "navy", or transparent) |
--gradient NAME |
— | One of the 8 presets above |
--padding N |
40 |
Padding around the image (px) |
--shadow N |
32 |
Drop shadow blur radius (px) |
--no-shadow |
— | Disable drop shadow |
--round N |
8 |
Rounded corner radius (px). Set 0 for sharp corners. |
--no-crop |
— | Skip auto-crop step |
--bg-tolerance N |
8 |
Color distance tolerance for edge detection (raise it if your screenshot has subtle gradients in the margin) |
--browser |
— | Wrap in fake browser window with traffic lights + URL bar |
--macos |
— | Wrap in macOS-style window with traffic lights only |
--width N |
— | Resize final output to this width (px), keeps aspect ratio |
--suffix STR |
_pretty |
Output filename suffix |
--inplace |
— | Overwrite the original file |
--backup |
— | With --inplace, save a .bak before overwriting |
--quality N |
92 |
JPEG / WebP quality (1–100) |
Exit codes: 0 = all images processed, 1 = at least one failed, 2 = bad arguments / nothing found.
- Auto-crop. Samples the four corners, picks the most common color as the background, then walks the bounding box inward until pixels diverge by more than
--bg-tolerance. Anti-aliased fades along the border are included thanks to the tolerance. - Window chrome (optional). Adds a top bar (browser URL bar or macOS traffic lights) before the rest of the pipeline so the shadow envelops the whole thing.
- Rounded corners. Mask-blits the image through a rounded-rectangle alpha mask.
- Drop shadow. Takes the alpha channel, pads it on a transparent canvas, applies a Gaussian blur, fills it with semi-transparent black, then composites the original on top.
- Background canvas. Generates either a vertical linear gradient or a solid color the size of
image + padding * 2, then alpha-composites the shadowed image onto it. - Resize (optional). LANCZOS resample to
--widthif given.
.png, .jpg, .jpeg, .webp, .bmp, .tiff. JPEGs are flattened onto white before saving (since JPEG can't carry an alpha channel).
Use them. They're great. prettyshot exists for the cases those don't cover:
- Batch processing 50+ screenshots for a docs site or release notes.
- CI/CD pipelines that need to polish screenshots committed by automation (visual regression tests, marketing site previews).
- Reproducibility — same image, same flags, same output across the team. No "I forgot which preset I used."
- Free, scriptable, no subscription, no per-machine license.
prettyshot runs entirely locally. It opens the image files you point it at, processes them in memory, writes outputs back next to them. It never makes a network request and never sends anything anywhere.
MIT — see LICENSE.