README GIFs that are small, sharp and smooth.
The first thing people see on your repo. Record the feature, let Dolly zoom on it, and export a GIF that loads fast on GitHub, in docs and in pull requests.
How do you make a GIF for a GitHub README on a Mac?
Record a tight area around the feature with Dolly, keep it to 3 to 10 seconds, and turn on Loop position so the cursor ends where it started. Export as GIF at 720 px wide and 10 to 15 fps; Dolly shows the estimated file size first, and the Docs GIF preset keeps it under GitHub's 10 MB limit. GIF export is part of Lifetime (€5 once).
Who it’s for: Open-source maintainers, developer-tool makers and technical writers.
Record the feature.
A tight area around the part that matters.
How to make a README GIF in Dolly.
4 steps, most of them automatic.
- Record a tight areaArea recording around the part that matters. A smaller source gives a smaller, sharper GIF.
- Keep it short3 to 10 seconds. Trim to the action and speed up any typing.
- Make it loopTurn on Loop position in the cursor settings so the end flows into the start.
- Export GIF720 px wide at 10 to 15 fps is the sweet spot. Check the size estimate, or use the Docs GIF preset to fit under 10 MB.
Settings that work, and what to avoid.
Recommended settings
- Format
- GIF (Lifetime)
- Width
- 720 px (480 px for inline docs)
- Frame rate
- 10 to 15 fps
- Loop
- On
- Size
- Under 10 MB for GitHub
Mistakes to avoid
- Recording the whole screen. Record an area around the feature instead.
- Long GIFs. Past about ten seconds, an MP4 is far smaller.
- 30 fps. A much bigger file for little visible gain in a UI loop.
- A jump at the loop point. Turn on Loop position.
GIF or MP4 on GitHub?
GIFs autoplay anywhere a Markdown image works, including READMEs, but they get big fast. Videos uploaded through GitHub's editor play in READMEs, issues and pull requests as a player, at a fraction of the size. For a short loop, GIF; for anything longer than about ten seconds, MP4.
Dolly or a converter
You can also record with ⇧⌘5 and convert with ffmpeg or Gifski. That works. Dolly adds the zoom, the smooth cursor and the frame, and does the conversion in the same export. The GIF guide has the numbers and an ffmpeg recipe.
README GIFs: questions
How do I turn a screen recording into a GIF on Mac?
In Dolly, choose GIF at export and pick a width, frame rate and looping. Or convert an MP4 with ffmpeg, using a palette for better colors.
What size should a README GIF be?
About 720 px wide at 10 to 15 fps, a few seconds long, and under GitHub's 10 MB limit for images.
Can I make README GIFs with the free version?
Free exports MP4, which GitHub also plays in READMEs, issues and pull requests. GIF export comes with Lifetime, €5 once.
Why is my screen recording GIF so big?
GIF size grows with width, frame rate, length and how much of the picture changes. Record a smaller area, cut to the action and use 10 to 15 fps.
Does GitHub play MP4 videos in a README?
Yes, when you upload the video through GitHub's web editor. It shows as a player instead of autoplaying like a GIF.
Related
Roll camera.
Free to use, with no time limit. Everything for €5, once.
First time: open Dolly, click Done, then System Settings → Privacy & Security → Open Anyway (macOS 13–14: right-click Dolly → Open). Once only. Installation help