GitHub README GIF: How to Make a Demo GIF That Stays Small

A good GitHub README demo GIF is 5 to 8 seconds long, 640 to 800 px wide, at 10 to 12 frames per second, and under about 5 MB. GitHub accepts images and GIFs up to 10 MB as uploads, but a GIF that size makes the first screen of your README slow to load. GIFs get big fast: in our test, a 7.5-second clip with a moving camera needed 640 px at 10 fps to get under 5 MB, while the same clip as an MP4 was 0.27 MB. So build the GIF with ffmpeg's palette filters, keep the motion small, and for anything longer or with sound, upload an MP4: GitHub plays videos in READMEs too.

Below are the limits, the file sizes we measured for one clip at different settings, and copy-paste commands.

#What are GitHub's limits for GIFs and videos?

The 10 MB is a ceiling, not a target. A README is often the first thing a visitor sees, and the GIF loads before they decide whether to scroll.

#How big is a README GIF at different settings? What we measured

We exported a 7.5-second clip of a sample developer tool from Lumora at 1920x1080, with a slow camera move and one callout, and encoded it with ffmpeg at different widths and frame rates using the palette method below. We made two versions: one on a plain dark background, and one on a photo wallpaper (Lumora's Studio look).

Four things stand out:

• Only small, slow GIFs fit. With a moving camera, only 640 px at 10 fps came in under 5 MB. Anything 800 px or wider was 7 MB or more.
• Width and frame rate both count. Dropping from 960 px at 15 fps to 640 px at 10 fps cut the file by almost two thirds. UI motion reads fine at 10 fps.
• Busy backgrounds cost 25 to 40% more. The wallpaper version was 25 to 40% bigger at every setting, because GIF's 256 colours struggle with photos and gradients.
• MP4 is in another league. The same clip was 0.27 MB as an MP4, about 18 times smaller than the smallest GIF.

A camera that moves changes every pixel in every frame, which is the worst case for GIF. A screen where only a small part changes (a terminal printing lines, a button being clicked) compresses much better, because the encoder can store just the changed rectangle. For a README GIF, a still camera beats a cinematic one.

#How to make the GIF with ffmpeg

GIFs only have 256 colours, so the quality comes from the palette. Generate a palette from your clip, then use it:

# 960 px wide, 12 fps, palette built from this clip
ffmpeg -i demo.mp4 -vf "fps=12,scale=960:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" demo.gif

# Smaller: 800 px, 10 fps, and limit the palette to the colours that change
ffmpeg -i demo.mp4 -vf "fps=10,scale=800:-1:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" demo-small.gif

stats_mode=diff builds the palette from the parts that differ from the previous frame, and diff_mode=rectangle processes only the smallest rectangle that changed. On our moving-camera clip they saved only 1 to 25%, because nearly everything changed every frame; they help most when large parts of the screen stay still. The options are documented in the ffmpeg filters reference.

#GIF or MP4 in a README?

Since May 2021, GitHub has supported video uploads everywhere you write Markdown, including repository Markdown files such as READMEs. Drag an MP4 into the editor and GitHub hosts it and inserts the link.

Use a GIF for the one thing that should move the moment someone opens the repo. Use an MP4 for a longer walkthrough, a talk-through with sound, or anything over about 15 seconds. Many projects do both: a short GIF at the top, a longer video further down.

#Where should the GIF live?

• In the repository, under docs/ or .github/, and linked with a relative path. GitHub transforms relative image paths so they work on every branch. The catch: every version you commit stays in the git history forever, so re-recording a 5 MB GIF every release makes every clone heavier.
• As an upload, by dragging it into an issue or the README editor. GitHub hosts the file and your history stays small.

For a GIF you update often, upload it. For one that rarely changes, keeping it in the repo is fine.

#Light and dark mode versions

GitHub's own writing quickstart shows how to swap images by theme with a <picture> element:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/demo-dark.gif">
  <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.gif">
  <img alt="Demo: deploying a branch and rolling it back in two clicks" src="docs/demo-light.gif">
</picture>

Only do this if your product has both themes and the GIF looks wrong on one background. Two GIFs means twice the work every time the UI changes. Always write real alt text: it's what screen readers and search engines get.

#What should a README GIF show?

• The one command or click that makes people get it. The install-and-run moment for a CLI, the core action for an app.
• Real output. If it's a CLI, show the real command and the real result, not a mock.
• Big enough text. A GIF scaled down to 800 px makes 13 px UI text unreadable. Zoom into the part that matters instead of showing the whole screen.
• A clean loop. End on a frame that leads back into the first, or hold the final state for a second so the restart doesn't feel like a glitch.

#Making README GIFs with Lumora

Lumora (ours) exports GIF, MP4 and WebM from the same project, and the Studio look keeps the screen flat on a soft wallpaper with zooms that do the moving, which compresses better than full 3D camera moves. If your team ships with Claude Code or Codex, the Lumora MCP server can render a fresh README GIF and a changelog clip as part of each release. For the tighter settings in the table above, take Lumora's MP4 and run the ffmpeg command on it.