How to turn a Mac screen recording into a GIF

A short GIF is still the easiest way to show a feature in a README, a pull request or a docs page. It plays on its own, loops forever, needs no player and works almost everywhere Markdown does. The catch: GIF is an old format, and a careless export easily turns a five-second clip into a 40 MB file that GitHub refuses to upload. This guide covers what makes a good screen GIF, the limits to keep in mind, and three ways to make one on a Mac.

GIF or MP4?

Before you make a GIF, check whether a video would do the job better.

	GIF	MP4
Autoplays and loops in a README	Yes	Plays with controls; no autoplay loop
File size for the same clip	Large	Often 5 to 10 times smaller
Colors	Max 256 per frame	Full color
Sound	No	Yes
Works in email, chat, old tools	Almost everywhere	Mostly

Use a GIF for short, silent loops: a button click, a drag-and-drop, a terminal command. Use MP4 for anything longer than about 15 seconds, anything with sound, and anything with lots of color gradients or photos.

Know the limits

Where your GIF is going decides how big it can be. On GitHub, the documented limits for attached files are 10 MB for images and GIFs. Videos are capped at 10 MB in repositories owned by a free-plan user or organization and 100 MB for paid plans. Many docs tools and chat apps have similar limits, and a big GIF also slows down the page for everyone who opens it.

A realistic target for a README GIF is under 5 MB, and under 2 MB is better.

What makes a good screen GIF

File size in a GIF comes from three things: pixel size, number of frames, and how much changes between frames. Control all three.

Keep it short. 3 to 10 seconds. One action per GIF. If you need to show three things, make three GIFs.
Make it narrow. 480 to 720 pixels wide is plenty for most READMEs. A README column on GitHub is well under 1,000 pixels wide on desktop, so anything bigger is downscaled anyway.
Lower the frame rate. 10 to 15 frames per second looks smooth enough for UI. 30 or 60 fps doubles or quadruples the size for little visible gain.
Record a small area. Record only the window or region that matters, not your whole 5K display. Fewer pixels to begin with means a sharper result after scaling.
Zoom in instead of going wide. A zoom on the important part keeps text readable at 600 pixels wide.
Avoid busy backgrounds. Gradients and photos eat into the 256-color palette and add noise. A plain or subtle background compresses better.
Make the loop seamless. End where you started: cursor back in the same place, same screen. Then the loop doesn't jump.
Hide the cursor when it isn't needed. A cursor sitting still in a corner adds nothing.

Option 1: Dolly

Dolly records your screen, adds the camera work, and exports GIFs directly.

Record an area. Press ⇧⌘2 and draw a rectangle around the part of the app you want. Do the action once, calmly.
Trim tight. Cut the start and end so the GIF begins right before the action. Split with S, delete what you don't need.
Zoom. Clicks become smooth zooms automatically; drag or delete them, or press Z for a manual zoom.
Clean the cursor. The cursor is redrawn and smoothed. Turn on "hide when idle", and loop the cursor position so it ends where it started.
Blur secrets. Use a blur mask over tokens, emails or customer names.
Export as GIF. Pick 480, 720 or 1080 px wide, a frame rate, and whether it loops. Dolly shows an estimate of the file size before you export, so you can drop the width or frame rate until it fits.

GIF export is part of Dolly Pro (€9.99 a month or €59 a year) and Lifetime (€99 once). The free version exports MP4 up to 1080p, with a small Made with Dolly logo in the corner. More on this in README GIFs with Dolly and on the pricing page.

Option 2: Kap or Gifox

Kap is a free, open-source screen recorder for Mac that exports to GIF, MP4 and WebM. It's simple and does the job for quick captures, without zooms or cursor effects. Gifox is a paid Mac app built specifically around GIF recording, with good size controls. Both are good choices if all you ever need is a quick GIF.

Option 3: ffmpeg

If you already have a screen recording (from the Screenshot toolbar with ⇧⌘5, QuickTime, or any recorder), ffmpeg can turn it into a high-quality GIF. Install it with Homebrew (brew install ffmpeg), then run:

ffmpeg -i recording.mov -vf "fps=12,scale=720:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" -loop 0 demo.gif

What each part does:

fps=12 drops the frame rate to 12 frames per second.
scale=720:-1:flags=lanczos resizes to 720 pixels wide and keeps the aspect ratio, with a sharp scaler.
palettegen and paletteuse build a custom 256-color palette from your clip and apply it. This is what makes ffmpeg GIFs look far better than a naive conversion. The ffmpeg filter docs explain the options.
-loop 0 makes the GIF loop forever.

To cut the clip at the same time, add -ss 2 -t 6 before -i to start at 2 seconds and keep 6 seconds. If the file is still too big, lower the width to 600 or 480, or the frame rate to 10.

Checking the result

Before you commit the GIF:

[ ] It's under the size limit of where it's going (aim for under 5 MB).
[ ] Text is readable at the size it will be displayed.
[ ] The loop doesn't jump at the end.
[ ] No tokens, emails or private data are visible.
[ ] It starts within half a second of the action.

Putting it in a README

In Markdown on GitHub, either drag the GIF into an issue or pull request comment (GitHub uploads it and gives you a link), or commit it to the repository and reference it:

![Creating a new note](docs/new-note.gif)

Put the GIF right under the heading it illustrates, and write alt text that describes the action, so the README still makes sense for screen readers and when images don't load.

For longer demos, export an MP4 instead and keep the GIF for the one moment that sells the feature. See also vertical screen recordings if the same clip needs to go to social media, and bug report videos for GIFs in issues.