Make a GitHub README GIF people actually watch

Short answer: the README GIF is your repo's 6-second sales pitch, it autoplays inline where a video won't. Aim for 6–15 seconds, ~1000px wide, under 10MB, showing exactly one flow. Record it once with auto-zoom so the viewer's eye is steered, export as GIF, done.

Why the GIF is still king on GitHub

Markdown renders images, including animated GIFs, inline and autoplaying. No click, no player chrome, no leaving the page. A repo with a good demo GIF converts a skimmer into a reader in the first screenful.

The one-take method

1. Script one flow. Install → run → result, or open → click → outcome. One narrative, no detours.
2. Record the window, not the screen. Your terminal or app window at a clean size; hide notification noise.
3. Let the zoom do the pointing. Girato builds zooms from your clicks, so the eye follows the action without you annotating anything.
4. Trim ruthlessly. Cut pauses (silence auto-cut helps), speed up waits with a speed ramp.
5. Export GIF. Girato caps GIF renders at sensible dimensions for exactly this use.

Budget the bytes

• Every second of GIF is expensive, 10s at 1000px is already megabytes. Shorter beats smaller-scaled.
• Flat UI compresses well; animated gradients and video backgrounds don't. Keep the backdrop simple for READMEs.
• If you need 30+ seconds, that's a video for your docs site, not a README GIF, link it under the GIF instead.

Recipe in practice: exporting GIFs from a screen recording covers the settings; the browser app lets you produce one right now.

Frequently asked questions

What's the ideal size for a README GIF?

• Under ~10MB, 6–15 seconds, around 1000–1280px wide.
• GitHub's attachment limit is higher.
• But big GIFs make your README feel slow.
• GitHub renders READMEs at ~890px content width.
• So massive dimensions waste bytes.

GIF or video in a README?

• An optimized GIF, for the README hero moment.
• It is still the most reliable choice.
• GIFs autoplay inline everywhere GitHub renders markdown.
• GitHub also accepts MP4 attachments in issues/PRs.