Why a GIF earns its place in a README
Nobody clones your repo on faith. They scroll the README, and the thing that makes them stay is seeing it actually work. A 5-second loop of your CLI spitting out output, or your app responding to a click, does more than a wall of usage examples. GitHub renders animated GIFs inline in Markdown, autoplays them, and loops them forever, so a demo right under your project title earns trust fast.
The catch is that GIF is a terrible video codec wearing a trench coat. It's 256 colors, no real motion compression, and it balloons fast. A careless 20-second screen capture can hit 30 MB and turn your README into a slideshow on slow connections. The whole game is keeping it short, small, and legible. That's what the controls below are for.
The GitHub size limits you actually need to know
Two numbers matter. GitHub caps any single file committed through the web interface at 25 MB, and the ceiling for a file pushed via git is 100 MB before it warns or rejects. But those are the technical walls, not your target. A README GIF that loads instantly should sit somewhere between 2 MB and 8 MB. Past that, mobile readers and anyone on hotel wifi watch a gray box.
You have two ways to host it. You can commit the GIF into the repo (often in a docs/ or assets/ folder) and reference it with a relative path, which keeps it under version control and works offline in clones. Or you can drag the finished file into a GitHub issue or the README editor and let GitHub serve it from its user-content CDN, then paste the resulting URL. The first keeps everything self-contained, the second keeps your repo lean. Either way, smaller is better, so build the file small from the start.
Record the demo, then bring the file here
What the GIF converts a video file into a GIF, entirely inside your browser tab. It does not record your screen, so you'll capture the demo with whatever you already have: macOS users hit Cmd+Shift+5, Windows users reach for the Xbox Game Bar, Linux users use OBS or Kazam. Save it as MP4 or MOV and you're set. If you grabbed it from a meeting or a longer capture, the screen recording to GIF page covers that exact workflow.
Then drag that file into the converter. The video never leaves your machine. There's no upload, no account, no server crunching your footage in some datacenter, which is the right default when the recording shows internal tooling or a half-finished feature. It's all client-side JavaScript, so it works the same on a Mac, a Windows box, or a Chromebook, and it keeps going if your wifi drops mid-edit. If staying offline is the whole point, the video to GIF without uploading page explains exactly how that works.
Settings that keep text crisp and the file small
A GIF in a GitHub README lives or dies on two things: readable text and a small file. Here's how to get both at once.
- Trim ruthlessly. Use the frame-accurate timeline to cut to just the moment that matters. Nudge the in and out points a single frame at a time with the arrow keys. A tight 4-to-6-second loop beats a rambling 15-second one on every axis: size, clarity, and whether anyone watches the whole thing.
- Drop the frame rate to 10 to 15 fps. A terminal demo or a UI click doesn't need 30 fps. Ten frames a second looks fine and roughly halves the file versus 24. Smooth cursor motion is the only reason to go up to 15.
- Downscale to your display width. A README column renders around 900 px wide on desktop and much less on mobile. Scale the output to something like 800 px wide (or less for a terminal recording) instead of dumping a full 1440p capture. This is the single biggest size lever you have.
- Tune the palette and dithering. GIF tops out at 256 colors, and for screen and code you rarely need them all. Try 64 to 128 colors and watch the live size estimate. Flat UI and monospace text stay crisp at the low end, while busy photographic footage needs more. Dithering trades a little file size for smoother gradients, so toggle it and compare.
- Crop to what counts. Lock to 16:9 for a wide app window or 1:1 for a square terminal pane, and chop off the menu bar, the dock, and any empty desktop. Fewer pixels means a smaller file and a demo that points the eye exactly where you want it.
The live estimated file size updates as you adjust, so you're never guessing. Watch it cross under your 2-to-8 MB target before you export. If you're optimizing hard for tiny, the small-file GIF from video page goes deeper on squeezing every kilobyte.
Drop it into the Markdown
Once the GIF is in your repo or hosted by GitHub, the Markdown is one line. Reference it like any image:
- Relative path, committed to the repo: 
- GitHub-hosted file: 
- Wrap it in a link if you want clicking the GIF to open a full video or docs page: [](https://your-docs-link)
Put it high, right under the project title and one-line description, so it's the first thing on screen. Add concise alt text in the brackets for screen readers and for the moment GitHub's CDN hiccups and the image doesn't load. That's it. Commit, push, and your README now shows instead of tells. The same file works anywhere Markdown does, so if you're also shipping a product demo GIF elsewhere, you can reuse it without re-exporting.