Regressive JPEG: A Postmortem on Baseline-Fallback Regression
Background and Motivation
For years the standard advice in every web-performance guide was simple: export progressive JPEG. On slow networks a progressive JPEG paints the entire frame in a blurry first scan, then refines it across subsequent scans, so users see composition almost immediately instead of the dreaded top-to-bottom " Venetian blind" reveal of a baseline image. Perceptual time-to-first-frame drops, bounce falls, the experience is meaningfully better.
Then two things happened.
- WebP and AVIF became the default delivery format for everything except email and legacy CMS pipelines, so JPEG handling quietly fell off the radar of many teams.
- Static-site generators and image-processing pipelines silently re-encode any image that passes through them. Hugo, for instance, uses Go’s
image/jpegpackage — and as the Hugo Discourse thread on “Progressive JPEG defaults to baseline after image processing” documents, the standard Go encoder has never emitted progressive JPEG. Take a perfectly good progressive JPEG, run it throughResources.Resize, and the output silently becomes baseline. The file extension is the same. The visual quality is the same. Only the internal scan structure — and the loading behavior — is gone.
This is the class of bug this article calls a regressive JPEG: a JPEG that was progressive upstream and regressed to baseline downstream without anyone noticing. The canonical postmortem pattern is:
- A designer exports hero images as progressive JPEG.
- A build pipeline resizes / crops / recompresses them.
- The deployed artifact is baseline.
- Performance dashboards do not move because LCP measures the final rendered bytes, not intermediate scans. The regression is invisible to synthetic monitoring.
- Real users on EDGE / 3G / congested Wi-Fi start complaining about “images loading slow” with no metric to correlate against.
The purpose of this article is to make this class of regression visible, reproducible, and CI-trappable.
Prerequisites
- A POSIX shell and
file(BSD or libmagic) for signature inspection. libjpeg-turbotooling, specificallyjpegtrananddjpeg— available aslibjpeg-turbo-progs/libjpeg-tools/libjpeg-progsdepending on your distro.- Optional:
mozjpegif you want lossless re-progressive-ization. - An existing image pipeline you can run end-to-end (Hugo, Eleventy, Next.js
next/image, a Railsactive_storagevariant, anything that calls an encoder under the hood). - familiarity with a hex-dump tool (
xxd/hexdump -C) — not required but clarifying.
Step 1: Preparation
The first thing to internalize is that progressive vs baseline is not a quality setting — it is a file-structure variant. Both encodings use the identical DCT-based lossy pipeline. The difference is purely how the resulting quantized coefficients are laid out in the byte stream:
- Baseline: coefficients for every 8×8 MCU are written fully, in raster order, MCUs top-to-bottom.
- Progressive: coefficients are split into multiple scans. Early scans carry low-frequency DCT coefficients (DC + a few ACs) at full frame resolution; later scans fill in higher-frequency coefficients.
Because of this, you can convert between the two without any re-loss by simply rescanning the existing_entropy-coded data. jpegtran -progressive does exactly that — it repacks the bitstream without touching the dequantized coefficients. Similarly, jpegtran -baseline does the inverse. Neither operation changes the visual content; only the scan ordering does.
Practical implication: any tool that round-trips through a decode-then-encode (ImageMagick convert, Go’s image/jpeg.Encode, libvips in lossy mode) will re-encode and has an opportunity to write baseline even if the input was progressive. Tools that call jpegtran under the hood (mozjpeg does this for lossless operations) preserve the existing scan structure unless told otherwise.
For this article, prepare a single test image:
# Make sure you have jpegtran available
command -v jpegtran || sudo apt-get install -y libjpeg-turbo-progs
# Prepare a reasonably sized source JPEG (something a hero pipeline would produce)
curl -sL -o /tmp/source.jpeg https://www.gstatic.com/webp/gallery/1.jpg
ls -l /tmp/source.jpegEstablish a baseline expectation:
# Convert the same image two ways for comparison
jpegtran -progressive -outfile /tmp/prog.jpeg /tmp/source.jpeg
jpegtran -baseline -outfile /tmp/base.jpeg /tmp/source.jpeg
wc -c /tmp/prog.jpeg /tmp/base.jpegTypical result: the progressive variant is within ±2% of baseline (often smaller, occasionally a hair larger for very small images). This is the cost band you operate in.
Step 2: Core Implementation
2.1 Detect the scan structure of a JPEG on disk
The JFIF structure (SOF0 = baseline, SOF2 = progressive) is enough for a cheap classifier that has no false positives on well-formed JPEGs:
#!/usr/bin/env bash
# jpeg-scan-type.sh — prints "progressive" / "baseline" / "unknown" for a JPEG file
# Uses the SOF marker to identify scan structure. Pure POSIX shell + hexdump.
set -euo pipefail
f="$1"
[ -r "$f" ] || { echo "unknown: $f not readable" >&2; exit 2; }
# SOF0 (0xFFC0) = baseline; SOF2 (0xFFC2) = progressive; SOF1 is extended sequential
# (rarely used); treat both sequential variants as non-progressive.
marker=$(hexdump -C "$f" | grep -m1 -oE 'ff c[02] ' | head -1)
case "$marker" in
*"ff c0"*) echo "baseline" ;;
*"ff c2"*) echo "progressive" ;;
*) echo "unknown" ;;
esacRun it:
$ bash jpeg-scan-type.sh /tmp/prog.jpeg
progressive
$ bash jpeg-scan-type.sh /tmp/base.jpeg
baselineIf the tool answers unknown the file is either truncated or uses a SOF marker we did not enumerate (SOF1, SOF3 lossless, arithmetic coding SOF9, SOF10…). For web production that almost never happens; if it does, pipe the file through djpeg -fast -ppm > /dev/null and treat any failure as “cannot decode, must re-encode.”
2.2 Lock the production pipeline to progressive
Most static-site pipelines cannot be told “keep my JPEG progressive” directly. The robust fix is to add a post-build pass that walks every generated .jpg / .jpeg and re-progressive-izes any file that came out baseline:
#!/usr/bin/env bash
# enforce-progressive-jpeg.sh — re-progressive any baseline JPEG in a tree.
# Idempotent: -progressive on an already-progressive file is a no-op.
set -euo pipefail
ROOT="${1:-public}"
count_baseline=0
count_skipped=0
while IFS= read -r -d '' f; do
# Skip already-progressive to avoid touching mtime unnecessarily
if hexdump -C "$f" | grep -qE 'ff c2 '; then
count_skipped=$((count_skipped+1))
continue
fi
# Rewrite in-place via a temp file so we never lose data if jpegtran explodes
tmp="$(mktemp --suffix=.jpeg)"
if jpegtran -copy none -progressive -outfile "$tmp" "$f"; then
# Guard against the well-known jpegtran 0-byte output on grayscale JPEGs
if [ -s "$tmp" ]; then
mv "$tmp" "$f"
count_baseline=$((count_baseline+1))
else
echo "WARN: jpegtran produced empty output for $f — left unchanged" >&2
rm -f "$tmp"
fi
else
echo "WARN: jpegtran failed on $f — left unchanged" >&2
rm -f "$tmp"
fi
done < <(find "$ROOT" -type f \( -iname '*.jpg' -o -iname '*.jpeg' \) -print0)
echo "enforce-progressive-jpeg: $count_baseline re-encoded, $count_skipped already-progressive"Hook this into your build script immediately after the static generator writes to public/ (or whatever your output directory is):
hugo --minify --gc
./enforce-progressive-jpeg.sh public/For a Hugo pipeline specifically, this is the only mechanism that works against image/jpeg.Encode. The Discourse thread quoted above is nine years old and the Go stdlib JPEG encoder still does not emit progressive output — patching the encoder is out of scope for most teams.
2.3 Add a CI guard that fails BEFORE the broken build ships
The script in 2.2 is a remediation; what you want in CI is a gate that fails the build the moment a JPEG leaves the test pipeline as baseline:
#!/usr/bin/env bash
# ci-jpeg-progressive-gate.sh — fail if any JPEG under public/ is baseline.
# Exits non-zero on the first baseline file found; CI then aborts the deploy.
set -euo pipefail
ROOT="${1:-public}"
violations=()
while IFS= read -r -d '' f; do
if ! hexdump -C "$f" | grep -qE 'ff c2 '; then
violations+=("$f")
fi
done < <(find "$ROOT" -type f \( -iname '*.jpg' -o -iname '*.jpeg' \) -print0)
if [ "${#violations[@]}" -gt 0 ]; then
echo "ERROR: ${#violations[@]} JPEG(s) are baseline (not progressive):" >&2
printf ' - %s\n' "${violations[@]}" >&2
echo "Run enforce-progressive-jpeg.sh $ROOT/ before deploying." >&2
exit 1
fi
echo "ci-jpeg-progressive-gate: all JPEGs are progressive ✅"Add it to your CI workflow:
# .github/workflows/build.yml (excerpt)
- name: Build
run: hugo --minify --gc
- name: Enforce progressive JPEG
run: ./enforce-progressive-jpeg.sh public/
- name: Gate — no baseline JPEG
run: ./ci-jpeg-progressive-gate.sh public/Step 3: Verification and Tuning
3.1 Byte-size sanity
Re-progressive-izing does not always save bytes. Empirically the change is in the ±2% band:
$ wc -c /tmp/base.jpeg /tmp/prog.jpeg
28544 /tmp/base.jpeg
28089 /tmp/prog.jpeg # ~1.6% smallerFor very small images (under ~10KB after optimization) the structural overhead of multiple scan headers can make the progressive variant slightly larger. The usual recommendation from the ShortPixel “Progressive JPEG vs Baseline JPEG: Does It Still Matter in 2026?” post is to use baseline for thumbnails below ~10KB. A reasonable tunable for the gate above:
# Skip gates for files below 10240 bytes; small files don't benefit from progressive scans.
size=$(stat -c%s "$f")
[ "$size" -lt 10240 ] && continue3.2 Decode-cost reality check
Progressive JPEG costs more CPU to decode — Google’s own measurement, quoted both by ctrl.blog and theimagecdn.com’s comparison guide, puts progressive decode at roughly 3× baseline on average. On high-end desktops this is unmeasurable. On low-end mobiles it can be visible in profile. Two mitigations:
- Reduce the number of scans.
jpegtran -progressiveuses a default scan script of about 14 scans.mozjpegships a tighter 4-scan script. Fewer scans ⇒ fewer decode passes ⇒ less CPU. - Use the “semi-progressive” pattern (3–6 scans) for hero imagery on mobile-heavy sites. Trade-off: a tiny bit less incremental sharpening during load, but a flat CPU profile.
3.3 Choose the right format for the right job
Progressive JPEG does not obsolete WebP/AVIF. The 2024 HTTP Archive Media chapter (cited by the image CDN article above) still has JPEG at 32.4% of mobile image resources — so JPEG fallbacks matter — but the headline recommendation is unchanged:
- Serve AVIF to browsers that accept it.
- Serve WebP to browsers without AVIF support.
- Deliver progressive JPEG as the final fallback, not baseline.
Concretely in HTML:
<picture>
<source type="image/avif" srcset="/hero.avif">
<source type="image/webp" srcset="/hero.webp">
<img src="/hero.jpeg" alt="Hero" <!-- this one should be progressive -->
loading="lazy" decoding="async">
</picture>And in CDN configuration, ask for format negotiation so the same origin URL serves the right bytes per Accept header.
3.4 Filter the well-known false negative
jpegtran will write a 0-byte file when given an already-grayscale JPEG and certain scan scripts. The script in 2.2 already guards against this with [ -s "$tmp" ] (test for non-empty file). Do not skip that test; you will lose data.
Best Practices Summary
- Treat progressive-vs-baseline as a file structure, not a quality setting. Your build pipeline’s re-encoder cares only about its
SOF0-emitting code path; it does not care that you imported a progressive source. - Add an explicit post-build
jpegtran -progressivepass for any pipeline (Hugo, Eleventy, Rails, etc.) that decodes-then-encodes images. Idempotent and zero-loss. - CI gate before deploy. A 30-line shell script that walks
public/**/*.jp(e)?gand refuses any file without an0xFFC2marker catches the regression in minutes, not in production. - Skip the gate for thumbnails under ~10KB. Progressive overhead can exceed its savings below that size; baseline is fine for thumbnails.
- Pair progressive JPEG with AVIF/WebP first. Modern
<picture>ordering: AVIF → WebP → progressive JPEG fallback. The progressiveness of the JPEG matters for the long-tail fallback audience, especially on EDGE / congested Wi-Fi. - Prefer
mozjpegover stockjpegtranfor production. It defaults to a tight spectrum-progressive scan script and provides measurable further byte savings beyondlibjpeg-turbo’s defaults without re-loss.
References
- ShortPixel — Progressive JPEG vs Baseline JPEG: Does It Still Matter in 2026?
- ctrl.blog — Progressive JPEGs make a meaningful impact on perceived performance
- The Image CDN — Progressive JPEG vs Baseline JPEG - Which Should You Use?
- Hugo Discourse — Progressive JPEG defaults to baseline after image processing
- web.dev — Learn Images: JPEG