How to Add a Demo GIF to Your GitHub README

To add a demo GIF to your GitHub README, record only the part of the screen that matters, keep the clip under 15 seconds, and export a GIF about 640 px wide. Commit the file to your repo, for example as docs/demo.gif, and add ![Demo of mytool](docs/demo.gif) to your README. GitHub shows GIFs inline and they loop on their own, so visitors see the project working before they read the install steps.

What a good README GIF shows

A README GIF has one job: show the core action in a few seconds.

• One action, start to finish. Run the command and show the output, or click the button and show the result. Leave out setup and secondary features.
• A tight frame. Show the terminal pane or the app window, not your whole desktop with the Dock and a browser tab bar.
• Text that's readable at the size GitHub displays it. GitHub scales images down to fit the README column, so a full-screen capture ends up with tiny text.
• 5 to 15 seconds. That's long enough to see the result and short enough to keep the file small and the loop from dragging.
• A clean loop. End on the result and hold for a beat before it restarts, so readers can take in the output.

Before you record, increase the font size in your terminal or editor, close unrelated tabs, and hide anything private. Our guide to making text readable in screen recordings has more detail.

Pick a tool for recording the GIF

The macOS Screenshot toolbar records your screen but saves a .mov, not a GIF. Every route therefore ends with either a GIF export or a conversion step.

For a plain capture of a terminal command, the free routes are enough. Screen Bolt helps when the GIF is part of how you present the project and you want it to look edited without opening a video editor.

Record a tight area

With the built-in macOS tools

1. Press ⇧⌘5 (Shift-Command-5) to open the Screenshot toolbar.
2. Click Record Selected Portion.
3. Drag the frame around the window or pane you want to show.
4. Open Options and choose where the file is saved. Under Microphone, choose None, since GIFs are silent.
5. Click Record and perform the action.
6. Click the stop button in the menu bar, or press ⌃⌘Esc (Control-Command-Escape).

You now have a .mov file. To turn it into a GIF, use our free video to GIF converter in the browser, or use ffmpeg in Terminal (covered below).

With Screen Bolt

Screen Bolt redraws the cursor so it moves smoothly. If Automatically create zooms is on, it also turns your clicks into zoom regions after recording.

1. In the recording bar, open Camera and choose Don't record camera. Open Mic and choose Don't record microphone. Open Audio and choose Don't record system audio. The bar remembers these choices, so switch them back for your next narrated video.
2. Decide whether you want automatic zooms. In a small, short GIF, a zoom can crop away context. To skip them, turn off Automatically create zooms in the Record menu before recording.
3. Click Area. The overlay reads "Drag to select recording area."
4. Drag around the region, then use the corner handles to adjust it. The overlay shows the selection's dimensions. Click Redraw to start over.
5. Click Record Area or press Return to confirm the selection.
6. Click the red record button. To save a step, Record ▸ Record area (⌥⌘5, Option-Command-5) opens the selection and starts recording as soon as you confirm. It only works while Screen Bolt is the active app.
7. Perform the action once, at a calm pace. If you make a mistake, click Discard and restart in the bar. That deletes the take without creating a project.
8. Click Stop. By default, the editor opens with your recording. Size the area to the GIF. A Standard GIF is 640 px wide and an HD GIF is 960 px wide. Mac screen sizes are measured in points (your display's "looks like" resolution). If your area is about as many points wide as the GIF is pixels wide, text in the GIF stays close to the size it had on screen. Squeeze a 1,280-point-wide area into a 640 px GIF and everything shows at half size. Padding around the recording shrinks the content a little more.

Keep the whole take short. Screen Bolt checks the GIF length limits against the full recording, not the trimmed result. A 90-second take trimmed down to 10 seconds is still refused. If a take runs long, record it again rather than trimming it.

Clean it up in the editor

All of these edits carry into the GIF.

• Trim the ends. Drag the left and right handles of the clip to remove the moment you reached for the mouse.
• Cut dead time. Press I at the start of a pause and O at the end, then click Cut I-O. This works well for a long wait on a build.
• Speed up the whole clip. The speed menu under the timeline (it shows "1x") offers 1.25x, 1.5x and 2x, and Screen Bolt applies that speed to the export. Don't use a speed ramp on a marked range for this: ramps play in the preview but aren't exported.
• Shrink the cursor. In the Cursor panel, Size defaults to 3.0×, which can cover UI in a small frame. Try a lower value and leave Smooth Movement on.
• Choose padding. In the Screen panel, set Padding to 0% to drop the background and get the tightest GIF. For a framed look, keep a small padding with a wallpaper background. Gradients and photos can look banded because a GIF frame is limited to 256 colors.
• Adjust or remove zooms. Right-click a zoom region on the zoom track and choose Delete This Region. In the Zoom panel, turning off Auto Zoom on Click disables every zoom region, including ones you added by hand. Screen Bolt GIFs run at about 10 fps, so a zoom animation gets only a few frames. If it looks jumpy, right-click the region and set Transition Speed to Snap (none).

Export a small GIF

1. Click Export in the editor toolbar.
2. Under Format, choose GIF.
3. Under GIF Size, choose Standard or HD (see the table below).
4. Next to Save to, click Change… and pick your repo's docs folder or wherever you keep assets. Screen Bolt remembers the folder.
5. Click Export or press Return.
6. Rename the file. Screen Bolt names it Screen Bolt <date> at <time>.gif. Spaces in file names are awkward in Markdown paths, so a name like demo.gif is easier to work with. | | Standard | HD | |---|---|---| | Width | 640 px | 960 px | | File size | Smaller | "Files can be 3–4× larger" (app text) | | Pick it when | The GIF shows a terminal, a small panel or a single interaction | The GIF shows a dense UI where small text must stay legible |

Neither size is ever wider than your recording. Both run at about 10 fps, loop, and have no audio. Your trims, cuts, speed, cursor, zooms and background are baked into the file.

Screen Bolt also applies two length limits. A recording over 15 seconds triggers a "Long GIF" prompt, and you can still click Export GIF to go ahead. A recording over 60 seconds is refused with "Clip Too Long for GIF."

GIF export is part of Screen Bolt Pro. The free version records and edits but can't export GIFs (compare Free and Pro).

Convert a recording with ffmpeg instead

If you recorded with ⇧⌘5, ffmpeg turns the .mov into a good GIF. It isn't built into macOS. If you use Homebrew, this command installs it:

brew install ffmpeg

This command converts the recording, skipping the first second and keeping the next 10 seconds:

ffmpeg -ss 1 -t 10 -i demo.mov -vf "fps=10,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" -loop 0 demo.gif

What the command does:

• Drops the frame rate to 10 fps and scales the width to 640 px.
• Builds a color palette from your clip, so colors look cleaner.
• Makes the GIF loop forever (-loop 0).

It writes a new file and leaves the original untouched. Replace demo.mov with your file name, and put the name in quotes if it contains spaces. For a wider GIF, use scale=960:-1.

Embed the GIF in your GitHub README

The simplest option is to commit the GIF and reference it with a relative path:

![mytool converting a CSV file to JSON in the terminal](docs/demo.gif)

The text in brackets is the alt text. Describe what the GIF shows: screen readers read it aloud, and it appears if the image fails to load.

GitHub allows an HTML img tag in READMEs, so you can use one to set the displayed width:

<img src="docs/demo.gif" alt="mytool converting a CSV file to JSON in the terminal" width="640">

To keep the GIF out of your repo, drag it into an issue or pull request comment box on GitHub. GitHub uploads the file and inserts Markdown with a hosted URL. Copy that line into your README. You don't need to post the comment.

This matters for GIFs you update often. Every version of a committed GIF stays in your git history, so the repo keeps growing. GitHub limits attachment sizes; check the current limits in GitHub Docs.

MP4 vs GIF on GitHub

Use a GIF for a short, silent loop at the top of the README. Use an MP4 for anything over about 15 seconds, anything with narration, or a walkthrough of several features. A short GIF at the top with a link to a longer video further down covers both.

To make the MP4 in Screen Bolt, export with Format set to MP4. The free version exports MP4 at 720p with a watermark and a 3-minute cap. Pro adds 1080p, 4K and Original. Presets larger than your recording are disabled, so a small area may only offer the lower sizes. The export docs cover the quality options.

Common mistakes

• Text is unreadable. The recorded area was much wider than the GIF. Record a smaller area, increase the app's font size, or switch to HD.
• The file is huge. The usual causes are length, HD for a simple UI, a gradient or photo background, or lots of motion. Shorten the take, switch to Standard, set Padding to 0%, and avoid scrolling through long pages.
• "Clip Too Long for GIF" after trimming. Screen Bolt measures the full recording, so record a shorter take.
• The GIF doesn't appear on GitHub. Check that the file is committed and pushed, and that the Markdown path matches the file name exactly. GitHub paths are case-sensitive, so Demo.gif and demo.gif are different files.
• Zooms look jumpy. At about 10 fps, animated zooms get few frames. Use Snap (none) or remove the zoom.
• The cursor jumps around. Move the mouse slowly while recording. Fast movement skips across the frame at GIF frame rates.

For more on GIFs of your screen, see how to record your Mac screen as a GIF. If you're weighing free recorders, our Kap alternatives page covers the options. For longer coding videos, read the guide to recording developer tutorials on macOS.