How to Add a Demo GIF to Your GitHub README

A demo GIF at the top of a README answers the first question every visitor has: what does this actually do? This guide covers how to add a demo GIF to a GitHub README from start to finish: recording a clip that reads well at README size, converting it to a GIF (or an MP4), keeping it small, and the markdown and HTML snippets to embed it, including a dark-mode version.

How to add a demo GIF to a GitHub README: the steps

1. Pick one feature and plan a 5–15 second clip that shows it working.
2. Record a small window with large text.
3. Trim the pauses before and after.
4. Convert to GIF at 640–800 px and 10–15 fps, or keep it as an MP4.
5. Store it in the repo (for example docs/demo.gif) or upload it through GitHub's editor.
6. Embed it with markdown or an <img> tag, and check the rendered README on desktop and phone.

GIF or MP4?

Both work on GitHub. GitHub renders uploaded .mp4 and .mov files as video players in READMEs, issues and pull requests when you add them through the web editor's drag-and-drop, which gives them a github.com/user-attachments/… URL. The difference is how they behave:

Our usual pattern: a short GIF at the top, so the README shows motion the moment it opens, and a longer MP4 further down (or a link to one) for people who want the full tour.

1. Record a clip that reads at README size

The README column is well under 1,000 px wide on a desktop and much narrower on a phone, so recording choices matter more than conversion settings.

• Record a small window, around 1000–1280 px wide, not a full Retina display. After scaling to 800 px, text stays legible.
• Make text big. Bump the browser zoom to 125% or the terminal font to 16–20 pt.
• Use a plain theme and background. Gradients and wallpaper waste the GIF's 256 colours.
• Clean up the prompt and paths. A short prompt like $, a demo directory, no usernames or hostnames, and no tokens in the scrollback.
• Move deliberately and pause a beat after each result so it can be read.
• Show one feature. The first GIF is a hook, not documentation.

We record ours with ZoomCap (we make it): the free browser recorder works in Chrome or Edge on any OS, and npx zoomcap record on macOS or Linux X11 zooms in automatically where you click and type, which is what keeps a small UI legible at 800 px. If you only need a raw capture, any recorder works: Shift-Command-5 on a Mac, the Snipping Tool or OBS on Windows, OBS or your desktop's recorder on Linux. More on the options for Mac in how to record your screen on a Mac.

2. Trim it

Cut everything before the first meaningful action and after the result has been visible for a second or two. Trimming is the biggest size saving there is: a GIF's size grows roughly in line with its length. With ffmpeg, -ss and -t trim during conversion (next step), so you don't need a separate editor.

If the loop should restart cleanly, end on the same screen you started on.

3. Convert it

The quickest way: our free MP4 to GIF converter does the conversion in your browser tab (tested by us; we built it). It converts the first 30 seconds of an MP4, WebM or MOV at up to 720 px wide and 12 fps, with no upload, no sign-up and no watermark. It has no trim or crop controls, so trim first. If you recorded in ZoomCap, skip this step and export the GIF from the editor.

If you want full control over width, frame rate and palette, use ffmpeg with a generated palette. This takes 8 seconds starting 2 seconds in, at 12 fps and 800 px wide:

ffmpeg -ss 2 -t 8 -i demo.mp4 \
  -vf "fps=12,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" \
  -loop 0 docs/demo.gif

We explain every option, plus gifski for higher quality and gifsicle for shrinking, in how to turn a screen recording into a GIF.

If you keep it as an MP4, make it small and widely playable before uploading:

ffmpeg -i demo.mp4 -vf "scale=1280:-2" -c:v libx264 -crf 24 \
  -pix_fmt yuv420p -movflags +faststart -an demo-small.mp4

Drop -an if you want to keep the sound.

4. Decide where the file lives

If you re-record the GIF often, the upload route keeps your repository lean. If the README is also published to npm, PyPI or crates.io, relative image paths may not resolve on those sites; check the rendered page there and switch to an absolute URL if the image is broken.

5. Embed it: markdown and HTML snippets

Plain markdown

![Demo: creating a project in three commands](docs/demo.gif)

Simple, but the GIF displays at its own width (up to the column). Write alt text that says what the demo shows, not just “demo”.

HTML with a fixed width, centred

<p align="center">
  <img src="docs/demo.gif" width="800"
       alt="Creating a project in three commands">
</p>

GitHub allows a limited set of HTML in markdown, including <img> with width and the align attribute. Setting width lets you export a slightly wider GIF for sharpness on high-density screens while displaying it at column width.

Different GIFs for dark and light mode

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/demo-dark.gif">
  <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.gif">
  <img src="docs/demo-light.gif" width="800"
       alt="Creating a project in three commands">
</picture>

GitHub serves the file that matches the viewer's theme. This doubles the recording work, so it is worth it mainly when the GIF has a transparent-looking edge or a background that clashes with one of the themes. A simpler alternative: record on a neutral mid-tone background that sits acceptably on both.

A GIF that links to the full video

[![Creating a project in three commands](docs/demo.gif)](https://example.com/full-demo)

An uploaded video

Drag the MP4 into the editor on github.com. GitHub inserts a URL on its own line, and the rendered README shows a player:

https://github.com/user-attachments/assets/<id>

Leave that URL on a line by itself; wrapping it in other markdown can turn the player back into a plain link. Preview before committing.

Size limits and targets

GitHub documents separate upload limits for images, GIFs and videos, and the video limit has differed between free and paid plans. We are not quoting numbers here because they change: check GitHub's current docs on attaching files before you rely on one. For files committed to the repository, GitHub's docs say it warns about files over 50 MB and blocks files over 100 MB in a normal push; a README GIF should never get close to either.

Our own targets, which keep the README quick to load:

• Top-of-README GIF: under 5 MB; about 10 MB at most.
• Secondary GIFs further down: 1–3 MB each, cropped tightly.
• Uploaded MP4: small enough to start quickly on a phone; a 30–60 second 1080p clip at CRF 24 is usually a few MB.

If you are over, trim, crop, drop to 10 fps or 640 px, or run gifsicle -O3 --lossy=80 (details in the GIF conversion guide). Some viewers turn off autoplaying animated images in their GitHub accessibility settings, so make the first frame meaningful on its own.

Terminal tools: generate the GIF from a script

For command-line tools, you may not need a screen recording at all. Two free tools produce crisp, small GIFs of terminal sessions:

• VHS (from Charm) reads a .tape script of commands and keystrokes and renders it to a GIF or MP4. Because it is scripted, you can regenerate the GIF in CI whenever the output changes.
• asciinema records a real terminal session as text; its agg tool converts the recording to a GIF.

# demo.tape (VHS)
Output docs/demo.gif
Set FontSize 18
Set Width 1000
Set Height 560
Type "mytool init my-project"
Enter
Sleep 2s

We compare these with real video, including when each is the better choice, in how to record a terminal demo that doesn't suck.

Tools

What we used or checked for this guide. ffmpeg, gifsicle, our converter and ZoomCap were tested by us; the others are described from their project pages.

Where ZoomCap fits: if your project has a GUI or a web interface and a raw capture looks small in the README, ZoomCap's editor zooms in on the action and exports a GIF or MP4 with a background and padding. Record in the free browser recorder (Chrome or Edge, zooms placed by hand) or with npx zoomcap record on macOS or Linux X11 (paid), which zooms automatically from your clicks. It costs $29 once (or $12.49/month). It is not the right tool for pure terminal demos (VHS or asciinema are smaller and sharper there), it has no Windows CLI, and on Linux the CLI records X11 sessions only. Recordings are edited and encoded on your computer and never uploaded; see the security page for how that works.

Frequently asked questions

Launching the project too? See how to make a Product Hunt launch video, and the ZoomCap docs for recording setup.

Make your README demo now. Record free in ZoomCap's browser recorder and export a GIF, convert an existing video with the free MP4 to GIF converter, or get unlimited watermark-free exports and automatic zoom for $29 once on the pricing page.