Add a Demo GIF to a GitHub README That Loads Fast

The Markdown is the easy part. The hard part is the file, so most of this post is about making a GIF that a stranger can read on a phone, on slow wifi, in the two seconds they give your repo before deciding whether to scroll. Every size below is a measured byte count from clips I generated for this post, not an estimate.

How do you embed a GIF in a README?

Add the file to your repository, then reference it with image syntax. GitHub's basic writing and formatting syntax page describes the form: an exclamation mark, alt text in square brackets, then the path or URL in parentheses.

![A short loop showing the install command running](docs/demo.gif)

Three details decide whether that line works:

1. Use a relative path for files in the repo. GitHub's README documentation says GitHub transforms a relative image path based on the branch you are currently viewing, and warns that absolute links may not work in clones of your repository. docs/demo.gif keeps working when you rename a branch or fork the project.
2. Write real alt text. It is what a screen reader announces and what shows if the image fails to load. Describe what the loop demonstrates, not "demo gif".
3. Match the case of the filename. Demo.GIF and demo.gif are different files on GitHub's servers even if your laptop does not care. This is the most common reason a GIF that works locally shows as a broken image on the repo page.

If the GIF still does not appear, check the path from the README's own folder first, then confirm the file is committed and pushed, not just sitting in your working directory. A GIF in a README at the repo root is referenced as docs/demo.gif; the same GIF referenced from docs/README.md is just demo.gif.

How large can a README GIF be?

GitHub documents this on its attaching files page, and it is a short list. As of 13 October 2026, the maximum file size there is 10MB for images and GIFs, and 25MB for all other files. Videos are 10MB on a free plan and 100MB on a paid one.

Two other limits sit underneath that, from GitHub's about large files page. A file added to a repository through the browser can be no larger than 25 MiB. GitHub warns on any file over 50 MiB pushed through Git, and blocks files larger than 100 MiB. Those are limits on what a repository will accept. None of them is a good target for a README image.

The practical reading is simple. If you drag a GIF into the editor, 10MB is the line. If you commit it with Git, the hard limits are far higher, but every clone downloads the file and it stays in history even after you replace it. A 9 MB GIF swapped three times is 27 MB of history. Aim for the smallest file that reads well, and treat 10MB as a wall you never get close to.

What width and frame rate keep code readable?

GIF has no motion compression. Every frame is stored as a near-complete indexed picture with at most 256 colours, so size tracks three things: how many frames, how many pixels per frame, and how much of each frame changes. I wrote up the mechanics in why a GIF balloons next to the MP4 it came from. For a README, that gives you a clear order of levers:

• Length. Linear and free. A five second loop costs half of a ten second one and loses nothing a visitor needed.
• Width. Quadratic. Halving the width quarters the pixels. A README column renders your image no wider than the content area, so exporting at 1920 pixels wide just ships pixels the page throws away.
• Frame rate. Linear. A typed command does not need 24 frames a second.
• Colour count and dither. Flat interface colours and dark code backgrounds survive a trimmed palette; photographic or gradient backdrops do not.

The generated palette matters too. A GIF built from a fixed generic palette turns a dark editor theme into mush. One built from the clip's own colours keeps syntax highlighting distinct. VidClip's GIF converter builds the palette from your footage in two passes, and the high-quality GIF walkthrough measures what that is worth.

What settings suit a terminal demo, a UI demo and an animation?

I generated three six second, 1280 by 720, 30 fps test clips with FFmpeg: a dark screen with scrolling lines of monospaced text, an interface-style clip with two coloured cards moving over a gradient backdrop, and a full-frame animation. Then I exported each at a "default" setting (24 fps, 1280 wide, the whole six seconds) and at README-friendly settings. Sizes are bytes divided by one million.

Terminal demo (dark background, text on screen)

Export	Width	Frame rate	Length	Size
Default	1280	24	6 s	7.44 MB
Full width, trimmed rate	1280	15	6 s	4.81 MB
README recipe	960	10	5 s	1.92 MB
README recipe	800	10	5 s	1.49 MB
Lean, 128 colours	800	10	4 s	0.93 MB

UI demo (moving cards over a gradient)

Export	Width	Frame rate	Length	Size
Default	1280	24	6 s	21.47 MB
Trimmed rate	960	15	6 s	10.67 MB
README recipe	800	12	6 s	5.45 to 6.24 MB
Lean	640	10	5 s	2.75 MB

Animation (full frame motion)

Export	Width	Frame rate	Length	Size
Default	1280	24	6 s	11.19 MB
README recipe	640	15	4 s	1.35 MB
README recipe	640	12	4 s	1.10 MB
Lean	480	12	4 s	0.74 MB

Three things stand out.

The default export fails for two of three clips. The interface clip lands at 21.47 MB and the animation at 11.19 MB. Both are over GitHub's 10MB cap for GIFs, so neither would attach through the editor at all. Only the dark text clip squeaks under, and at 7.44 MB it is still a heavy download for a project page.

Gradients are the expensive case. The interface clip needs more colours to avoid banding, so it stays large even after trimming: even the 960 pixel export is 10.67 MB, over the cap. If your product's backdrop is a gradient, crop to the part of the window that matters, or flatten the background before recording. Your README GIF does not have to show the whole app.

Text is the cheap case. A dark background and a few colours compress well. That is why a terminal demo can afford 800 pixels wide, where text stays legible, and still come in near 1.5 MB.

Use that as a starting recipe, then adjust by eye:

• Terminal or command-output demo: 800 pixels wide, 10 fps, 4 to 6 seconds. Start the clip on the frame where the command runs and end it as the output settles.
• Interface walkthrough: 800 pixels wide, 12 fps, up to 6 seconds, cropped to the panel being shown. Drop to 640 wide if the result is over 5 MB.
• Animation or visual effect: 640 pixels wide, 12 to 15 fps, 3 to 4 seconds. Motion needs frames more than pixels.

One honest caveat: these are synthetic test clips, not recordings of your project. Your numbers will move with how much of the screen changes between frames, which is the thing a scrolling log, a cursor blinking in an editor and a page transition all do differently. Treat the table as a map of which lever moves the number, then check your own export before committing.

Should the demo be a GIF or an MP4?

For most demos, an MP4 is far smaller. I encoded the same trimmed clips as H.264 at 28 CRF with the slow preset and no audio track: the terminal clip at 800 pixels wide and five seconds came out at 87 KB, the interface clip at 46 KB, and the animation at 640 pixels wide and four seconds at 100 KB. Compare those with 1.49 MB, 5.45 MB and 1.35 MB for the GIFs of the same content.

GitHub accepts video. The attaching files page lists MP4, MOV and WebM as supported, with a note that codec compatibility is browser specific and a recommendation to use H.264. Videos get playback controls, so a visitor can pause on the exact line you want them to read. A GIF cannot be paused.

So why use a GIF at all? Because of how it behaves in the page:

• A GIF is an image. It autoplays and loops with no click, works inside Markdown image syntax anywhere images work, and renders the same in the README preview, a package registry page that mirrors your README and most Markdown viewers that would show a video as a blank box.
• A video needs the platform to support it in that context. GitHub's editor handles uploaded videos, but a README is also read on registries, mirrors and documentation sites that may only render images.
• The loop is the message. A three second "type this, see that" belongs in a GIF. A two minute walkthrough belongs in a video, linked from the README.

My rule: if the demo is under about six seconds and the README will be read in places other than GitHub, use a GIF at the recipe sizes above. If it is longer, or the audience reads it on GitHub only, upload an MP4 and let people pause it.

How do you make the GIF from a screen recording?

Record the thing working with the recorder your system already has, and keep the take short. You can fix length afterwards, but you cannot add a clean ending to a recording that rambles. Save it as MP4 or MOV, then:

1. Open the recording in the browser tools, nothing uploads. The file is read into the page's memory and processed on your own CPU. No upload bar, no queue, no copy of an unreleased interface sitting on someone else's server.
2. Trim to the payoff. Start on the frame where the action begins and end just after the result appears. Four to six seconds loops well.
3. Crop to the part that matters if the full window is mostly empty space. Cropping cuts pixels per frame and makes the demo easier to read.
4. Open the video to GIF converter, set the frame rate and width from the recipe above, and download.
5. Check the file size, then check the GIF on a phone screen. If you cannot read the text there, raise the width by a step rather than the frame rate.

The same approach works for chat tools. If your recording is going to a channel instead of a repo, the Slack sizing guide covers the matching limits. Free GIF exports here carry a small corner mark, and Pro, at $4 a month or $79 once, removes it. For a one-off README demo, the free export is usually enough. For a project you will update every release, Pro removes the mark and lifts the 200 MB file cap.

Why is my GIF not showing in my README?

The usual causes, in the order to check them:

1. The path is wrong. Relative paths resolve from the README's own folder.
2. The case is wrong. Demo.gif is not demo.gif.
3. The file was never pushed. It exists on your machine but not on GitHub.
4. The file is too large to attach. Over 10MB, the editor upload fails.
5. The URL points to a page, not a file. Copy the raw file address or use the relative path.

FAQ

Why is my GIF not showing in my README? Almost always the path, the filename case or an unpushed file. Open the image URL directly in a browser. If that works, fix the path in your Markdown. If it does not, the file is not in the repository at that location.

Can I resize a GIF in GitHub Markdown? Markdown image syntax has no size control. The reliable fix is to export the GIF at the width you want it displayed, because then it is also the smaller file. HTML image tags with a width attribute are commonly used on GitHub, but a smaller export saves the download as well as the layout.

Where should README images live in the repo? In a dedicated folder such as docs/ or assets/, referenced with a relative path, as GitHub's README documentation recommends. If you attach images by dragging them into the editor instead, GitHub hosts them for you and gives back a URL. That keeps your repository lean, but the files then live outside your version history.

Do GIFs slow down a GitHub page? Yes, in proportion to their size. A README GIF downloads on every visit, and it autoplays, so a heavy one holds the project page's first impression behind a loading box. Keep it between 1 and 6 MB, and put long demos behind a link instead.

Make the GIF in your browser

Trim the recording, crop it to the part that matters, then export the GIF at README width with the video to GIF converter. The file never leaves your machine.