To add a GIF to a GitHub README, put the GIF file in your repository (for example in a docs or assets folder) and embed it with Markdown: . GitHub plays it automatically. Make the GIF from a screen recording with the MobileStudio Video to GIF tool, sized under about 5 MB so the README loads fast.
The short answer
| Step | What to do |
|---|---|
| 1. Record | Screen record the feature, a few seconds long |
| 2. Convert | Video to GIF, 640 px, 10 to 12 fps, 5 MB limit |
| 3. Store | Commit it to docs/ or assets/ in the repo |
| 4. Embed |  in README.md |
| 5. Check | Open the repo page and confirm it animates |
Why add a GIF to a README?
A GIF shows what your project does before anyone reads a word. It autoplays right on the repository page, which a video link can't do, and it's often the first thing visitors notice. For apps and CLIs, a short demo GIF is one of the most useful things a README can have.
How do I make a demo GIF for a README?
- Record your screen showing one feature. Keep it to 3 to 8 seconds. On Mac, Shift-Command-5 records a window or area; see how to make a GIF on Mac.
- Open Video to GIF and drop in the recording.
- Set the Start and Length to the key moment.
- Choose 5 MB as the size target, 640 px width, and 10 to 12 fps.
- Click Create GIF and save it as
demo.gif.
The tool rebuilds the GIF smaller if it goes over your limit, so you don't have to guess. More recording tips in how to turn a screen recording into a GIF.
What's the Markdown to embed a GIF?
The text in brackets is the alt text, which screen readers read aloud, so describe what the GIF shows. GitHub's formatting guide recommends relative links like docs/demo.gif for images stored in the repository, so they keep working in forks and branches.
To control the width, use HTML instead:
<img src="docs/demo.gif" alt="Demo of the app" width="600">
Where should I store the GIF?
In the repository itself, in a folder like docs/, assets/, or .github/. You can also drag a GIF into an issue or pull request comment, which uploads it to GitHub and gives you a link to paste in the README.
How big can a README GIF be?
Git warns about files over 50 MiB and blocks files over 100 MiB, as GitHub explains in About large files on GitHub. For a README, aim far lower: under 5 MB loads quickly even on slow connections. Shorter, narrower GIFs are the way to get there; see how to make a GIF smaller.
Should I use a video instead of a GIF?
For long demos, yes. A GIF over about 10 seconds gets heavy fast, and GIF's 256-color limit (described in the Library of Congress GIF overview) makes gradients look rough. Use a short GIF at the top, and link a full video below it. See GIF vs MP4.
How do I make a README GIF look good?
- Record at a normal window size, not full screen on a huge monitor.
- Use a clean demo account with real-looking data.
- Hide the mouse cursor when it isn't part of the story.
- Start on a meaningful screen, not a blank one.
- Loop it, so it plays forever.
Where MobileStudio fits
Video to GIF is one of our free tools. For a full demo video of your mobile app, MobileStudio adds device frames, smooth zooms, and backgrounds to your screen recordings. Get MobileStudio.
Quick FAQ
How do I add an animated GIF to a GitHub README?
Commit the GIF to the repo and embed it with .
Does GitHub play GIFs automatically?
Yes. GIFs in READMEs animate on the repository page.
What size should a README GIF be?
Around 640 px wide and under 5 MB.
Can I resize a GIF in a README?
Yes. Use an HTML img tag with a width attribute.
Why isn't my GIF showing on GitHub?
Check the path and file name case. Paths in GitHub are case-sensitive.
