GIF for a GitHub README
Show the feature instead of describing it. Nothing is uploaded.
The converter opens at 640 px and 12 fps with changed-pixels-only storage on — the settings that turn a short screen recording into a README GIF of one or two megabytes, which is about what a page can carry without slowing the first view. Drag the handles to the first click and the result, and check the estimate.
Open the converter → Opens the converter set to 640 px wide at 12 fps. Drag the handles to pick the part you want.- 100% freeNo account, no daily quota, no paid tier.
- Nothing is uploadedThe video is read and converted on your device and never reaches a server.
- No catch on the outputNo watermark, no forced downscaling, no size cap.
- Updated in the openEvery fix and every change is written down on the changelog page.
Why a GIF, and how big it can be
A GIF in a README plays without a click, on GitHub, on npm, on PyPI and in most places that render Markdown, which a video does not. That is the whole reason to accept its limits. Size-wise, a file committed to the repository can be up to 100 MB, but a README GIF is downloaded by every visitor on every view, so treat one or two megabytes as the budget and 5 MB as the ceiling. If you attach the GIF to an issue or a pull request instead of committing it, the attachment limit for images is 10 MB. GitHub does not re-encode README images, so the loop, the frame rate and the colours you see here are what readers see.
The README column is about 900 px wide on desktop and full-width on mobile. 640 px is a good default: text at a normal interface size remains readable and the file stays small; use 800 px for dense terminals or small fonts, and crop the recording to the relevant window rather than recording the whole screen.
Recording a demo that reads well
Record only the window that matters, at the size it will be read. Perform the action slowly — a reader is seeing it for the first time — and pause for a beat on the result before stopping; that pause costs almost nothing in a GIF because unchanged frames are merged into a longer delay. Then trim: drag the start handle to the first click and the end handle to a second after the result appears. Loop forever is the default, which is right for a README; readers who scroll past it and come back will see it playing.
Terminal and editor recordings compress best, since most pixels are flat; browser demos with photos or gradients compress worst. If a recording of a flat UI comes out larger than expected, turn dithering off under Advanced — it adds a fine pattern that counts as change. Commit the GIF next to the README (a docs/ or assets/ folder), reference it with a relative path, and it renders on GitHub and on the package registries.
Frequently asked questions
What is the size limit for images in a README?
A committed file can be up to 100 MB, but keep a README GIF to one or two megabytes: it loads on every view. Issue and PR attachments are limited to 10 MB.
Does GitHub re-compress GIFs?
No for files in the repository. The GIF renders as committed. Attachments in issues are also served as uploaded.
Should I use a video instead?
GitHub renders MP4 attachments in issues and PRs, but a README on GitHub, npm or PyPI needs an image. A GIF is the one format that autoplays in all of them.
Can I make the GIF play once?
Yes — untick "Loop forever" under Advanced. Most README GIFs loop so a reader who scrolls back sees it play again.