Skip to content
Lazygif
Menu
Open editor

Use case

GIFs for GitHub READMEs, pull requests and issues

A demo GIF at the top of a README answers “what does this do?” before anyone reads. In a PR, it saves the reviewer a checkout.

Open in the editorPreset: GitHub README
Width
800px
Frame rate
15 fps
Target
≤ 4.6 MB
Open an empty project

How to · 3 steps

Step by step

  1. 1

    Record the terminal or UI

    Capture a tab or window; Tidy up trims the ends and speeds up builds.

  2. 2

    Crop and redact

    Crop to the output and Blur tokens, paths or emails before it goes public.

  3. 3

    Export for GitHub

    The GitHub preset fits 10 MB; the README preset aims under 5 MB.

GitHub’s limits

GIFs attached to issues, PRs and comments can be up to 10 MB. A README GIF is downloaded by every visitor, so keep it under 5 MB and about 800 px wide; GitHub scales wider images down anyway.

Light and dark mode

A light UI glares on GitHub’s dark theme. Wrap the recording in a Background from the Canvas menu, with padding and rounded corners, so it reads as a card on either theme. Avoid GIF transparency: edges get a jagged halo.

Terminal demos and PRs

Shrink the terminal to about 100 columns before recording, and speed up long installs rather than cutting them. In a PR, put a before clip and an after clip side by side with a caption on each.

Size limits

Where this GIF is going

Limits for the destinations on this page. See every platform.

GIF size limits for GitHub issues & PRs, GitHub README
PlatformMax GIF sizeLazygif preset
GitHub issues & PRs
10 MB
800px · 15 fps · ≤ 9.2 MB
GitHub README
25 MB
800px · 15 fps · ≤ 4.6 MB

FAQ

Questions, answered

What is the GIF size limit on GitHub?
10 MB for images and GIFs in issues, pull requests and comments. Keep README GIFs under about 5 MB.
How do I add a GIF to a README?
Commit it (for example docs/demo.gif) and use that path in a Markdown image, or drag it into an issue comment and copy the link.
Why isn’t my README GIF showing?
If it’s hosted elsewhere, GitHub’s image proxy may refuse files over about 5 MB. Commit it to the repo, or shrink it with the README preset.

Related

Keep going

Make your first GIF now.

Record your screen or drop in a video. Free, no watermark, nothing uploaded.