DEV Community

GIF compressor workflow for READMEs, docs, and tickets

A four second screen recording can explain a bug faster than three paragraphs of description. Then you attach it and the upload box says 5 MB, and the file is 11 MB.

Most GIF work starts with a hard limit like that, and the number depends on where the file is going: a chat upload, a code host, and an issue tracker each set their own line. The fix is a short sequence of trades rather than one magic setting, made in an order that keeps text readable.

What follows is that sequence for GIFs headed into READMEs, docs, and issue tickets, with the commands and the arithmetic for hitting a target size.

Why a GIF gets large so fast

A GIF stores every frame as its own indexed image. MDN's format guide puts the constraint plainly: each pixel is an 8-bit index into a palette of at most 256 colors, and dithering is how a GIF fakes more colors than that.

Duration, frame rate, and pixel area all multiply into one number:

frames = seconds × frames per second

bytes ≈ frames × (palette cost of one frame)

A 4 second recording at 20 fps is 80 stored images. Shrink the window from 1200 px wide to 600 px and the frame count stays the same while the pixel area drops by about 75%, which is why resizing does so much for so little.

GIF also compresses poorly between frames. It can store only the rectangle that changed (the gifsicle manual calls this -O1, its default optimization level), and that helps a static interface recording a great deal. It stops helping the moment dithered gradients, shadows, or camera motion make most pixels change on every frame.

Measure before you change a setting

Two commands give you everything you need to plan the cut:

ls -lh demo.gif
gifsicle --info demo.gif

The first gives the byte count you have to beat. The second prints the frame count, the logical screen size, and the per-frame delay, which is the number you will need if you end up dropping frames.

Install gifsicle from your package manager (brew install gifsicle, apt install gifsicle) or run it from source; the gifsicle manual documents every flag below.

Then work out the ratio. Going from 9.4 MB to 3 MB means keeping 0.32 of the bytes. Square root that to get a linear scale factor, because file size tracks pixel area: sqrt(0.32) is about 0.57. So --scale 0.57 is a sensible first attempt, and the palette and lossy steps are the margin on top of it.

The four levers and what each one costs

Lever Flag Saves Costs
Scale --scale 0.65 or --resize-width 640 Scales with pixel area 1 px borders and small UI text go soft
Palette --colors 64 A lot on flat UI, less on photos Banding in gradients, dither noise in flat areas
Lossy --lossy=80 The most on GIFs made from video Visible artifacts once flat areas start mottling
Frames "#0" "#2" "#4" Close to proportional Motion becomes choppy

A few details matter in practice. --lossy defaults to 20 and larger values mean more artifacts and smaller files, so it is a dial rather than a switch. --colors accepts 2 to 256, and gifsicle may add a color for transparency, so a transparent GIF asking for 64 colors can end up with 65. --dither is off by default and turning it on makes files bigger, which is the opposite of what you want here.

Every one of those settings is a visible trade. That is the reason to change them one at a time and compare at the size the GIF will be viewed at.

The order that wastes the least quality

  • Scale down first. It is the most predictable reduction and costs the least visible quality per kilobyte saved.
  • Raise the lossy amount until artifacts appear in flat areas, then back off one step.
  • Cut the palette next, and watch gradients for banding.
  • Drop frames last. Choppy motion is the first thing a viewer notices.

That order also gives you a usable stopping point. If scaling and lossy already fit the limit, the palette stays at 256 and the animation keeps its timing.

A sequence you can run

# pass 1: scale only, plus optimization
gifsicle -O3 --scale 0.65 demo.gif -o demo-1.gif
# pass 2: add lossy compression
gifsicle -O3 --scale 0.65 --lossy=60 demo.gif -o demo-2.gif
# pass 3: cut the palette if still over
gifsicle -O3 --scale 0.65 --lossy=60 --colors 64 demo.gif -o demo-3.gif
# compare
ls -l demo.gif demo-1.gif demo-2.gif demo-3.gif

Keep the original untouched and write each attempt to a new file. Once one version fits, open it next to the original at 100% and compare a text-heavy region, not the whole frame.

One caveat on -O3: it does not promise a smaller file. The manual notes that optimization can occasionally enlarge a GIF, which is why the size check comes after every pass rather than only at the end.

Hitting a round number

Upload limits are almost always round numbers, and no compressor can hit one exactly without a search loop. You can get close in one pass with the area math above, then finish with a small correction: if the result is 15% over the limit, multiply the current scale by sqrt(0.85), about 0.92.

For a README that has to stay under 2 MB, the practical shape is a short clip at 600 to 800 px wide, 64 colors, and lossy 60. For a 5 MB ticket attachment, a 10 second recording at 900 px wide is the same kind of starting point, with --lossy=40 as a first pass and a size check before you attach it. Neither is a guarantee, because the result depends on how much of the screen changes.

If you want those four levers without a local install, a browser-based GIF compressor runs gifsicle compiled to WebAssembly inside the tab, so the file is never uploaded. It exposes presets called Light, Balanced, Strong, and Smallest plus the individual controls, and the Strong preset also scales to 75%. Two limits to know: it does not fit a file to an exact byte target, and the practical ceiling is your device memory rather than a fixed file size cap. The rest of the ShotEdit GIF tools, such as cropping, resizing, and speed changes, run on the same engine if a clip needs several passes.

Disclosure: this article comes from the team behind ShotEdit.

Dropping frames without speeding up the animation

GIF delay is stored in hundredths of a second. A 20 fps animation has a delay of 5, so keeping every second frame needs a delay of 10 to preserve the timing:

gifsicle --unoptimize --delay 10 demo.gif "#0" "#2" "#4" "#6" "#8" "#10" -o demo-half.gif

The manual defines --delay as the delay between frames, so the value covers every frame the command writes, rather than the first frame alone. --unoptimize matters here. An optimized GIF stores only the changed rectangle per frame, and the manual warns that this can make optimized animations difficult to edit. Unoptimizing first gives each frame a full picture to work from, at the cost of some memory during processing.

Frame selection follows the #num syntax, with #0 as the first frame and #-1 as the last, so a long recording can be cut with a range such as "#0-40" when only the start of the clip matters.

What to check before you commit the file

  • Text edges in the smallest UI label, at 100% zoom. Palette reduction hurts thin strokes first.
  • A 1 px border or divider. Lossy compression can make straight lines wobble.
  • Transparency on both a light and a dark background, since a single transparent color index can pick up a fringe.
  • Loop timing. A dropped frame or a changed delay is easy to miss on a fast machine.
  • The actual size on disk, after the last pass and not before it.

When the file refuses to shrink

Three cases come up often, and they need different answers.

A GIF that has already been through a compressor has no easy savings left. Pushing lossy higher keeps shrinking it, but artifacts show before the file gets meaningfully smaller.

A clip with very few colors is close to the floor already. A two color loading spinner has almost nothing for the palette and lossy controls to remove.

A long, full-width recording hits a format limit. If a 20 second capture at full width is still over a 5 MB chat limit after scaling, lossy compression, and palette cuts, more tuning usually will not close the gap. The fix is a shorter clip or a video.

When the GIF is the wrong format

If the target accepts video, conversion beats compression by a wide margin. web.dev's guide to replacing animated GIFs with video uses one example where a 3.7 MB GIF becomes a 551 KB MP4 and a 341 KB WebM:

ffmpeg -i demo.gif -b:v 0 -crf 25 -f mp4 -vcodec libx264 -pix_fmt yuv420p demo.mp4
ffmpeg -i demo.gif -c vp9 -b:v 0 -crf 41 demo.webm

Animated behavior comes back with <video autoplay loop muted playsinline>, and the article notes that a video without a poster image is not an LCP candidate, so a page that swaps in video may even improve its largest paint. GIF still wins where only an image is accepted, most clearly in inline email; that is a practical observation rather than something the article covers. Check what your destination accepts before you spend an hour on palette tuning.

A short summary you can paste into the repo docs

Work out the ratio, scale by its square root, then spend the remaining budget on lossy and palette before touching frames. Keep the original, write numbered attempts, and check the size after every pass. If the limit still will not budge, the clip is too long for the format, and the honest fix is a shorter clip or a video.

The next 10 MB recording follows the same steps, with the scale factor worked out before the first command runs.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.