Developer Tools
How to Add a GIF or Video to a GitHub README and Pull Request (2026)
Record your screen, turn it into a GIF or a small MP4, and embed it in a GitHub README, issue or pull request. Size limits, formats and the free browser tools to do it.
A ten-second clip of a feature working says more than three paragraphs of pull request description, and a looping demo at the top of a README is the fastest way to show what a project does. Getting there takes three steps: record the screen, make the file small enough, and put it where GitHub will render it. This guide covers all three, with the limits GitHub actually enforces and two free tools that do the conversion in your browser.
The short version
| You want | Use | Limit on a free plan |
|---|---|---|
| A demo in a pull request, issue or comment | MP4, dragged into the editor | 10 MB per video |
| A demo at the top of a README | GIF committed to the repo, or an MP4 attachment URL | 10 MB per image when attached |
| A demo that shows outside GitHub too (npm, docs sites) | GIF | depends on the host |
Paid GitHub plans raise the video limit to 100 MB. Images and GIFs stay at 10 MB.
1. Record the screen
Every desktop OS has a built-in recorder, and none needs installing:
- macOS — Cmd+Shift+5, choose Record Selected Portion, drag a box around the app. Recording a region rather than the whole screen is the single biggest size saving.
- Windows 11 — Snipping Tool's video mode, or Win+Alt+R in the Game Bar for one window.
- iOS Simulator — File → Record Screen, or
xcrun simctl io booted recordVideo demo.mov. - Android Emulator — the Screen record button in the extended controls, or
adb shell screenrecord /sdcard/demo.mp4.
Keep it short. Stop the recording as soon as the point is made; you can trim the start and end later, but every second you keep is bytes.
2. Make it small enough
A 30-second Retina screen recording is easily 40–80 MB. Two tools in the toolbox bring it down without uploading it anywhere.
For pull requests and issues: compress the video
The video compressor has a GitHub · 10 MB preset. It works
out the bitrate that fits your clip under the limit, can scale it to 1080p or 720p, and
re-records it in the page as MP4 (H.264) where your browser supports it. Untick Keep
audio for a silent demo and the picture gets the audio's share of the budget. It runs in
real time — a 30-second clip takes about 30 seconds — and it also turns a macOS .mov into
an .mp4.
Roughly what fits in 10 MB of clean screen recording: about a minute at 1080p, about two at 720p. Camera footage, where every pixel changes, needs more.
For READMEs: convert to GIF
The video to GIF converter takes the same recording, a start and end time, a frame rate and a width, and writes a looping GIF. Settings that work for most README demos:
- Width 640–800px. GitHub's README column is about 830px wide on desktop; wider only adds bytes.
- 10 fps. Smooth enough for UI; 15 fps for animations, 5–8 fps for typing demos.
- Under 10 seconds. Size grows with every frame.
The converter writes only the part of each frame that changed, and merges frames where nothing moved, so a recording of a mostly still window stays small. Aim for 1–5 MB: a GIF at the top of a README downloads for every visitor.
3. Put it on GitHub
In a pull request, issue or comment
Drag the MP4 or GIF into the comment box. GitHub uploads it and inserts a link on its own line; videos then play inline with controls, GIFs loop. That is all.
In a README
There are two ways, and they behave differently:
A GIF committed to the repository works everywhere the README is shown, including npm and most docs generators, because it is just an image:
A video only plays in a README when it is a GitHub attachment URL. Drag the MP4 into
any issue or pull request comment box, copy the https://github.com/user-attachments/…
link GitHub creates (you can discard the comment), and paste that URL on its own line in
the README. A relative path to an .mp4 in the repository renders as a plain link, not a
player.
The trade-off: the video is far smaller and sharper, but it will not render on npm or most docs sites. If the README is published anywhere else, use a GIF.
FAQ
What is the maximum GIF size on GitHub?
Images and GIFs attached to issues, pull requests and comments can be up to 10 MB. A GIF committed to the repository can be larger, but it should not be: every visitor to the README downloads it.
Can I put an MP4 in a GitHub README?
Yes, as a GitHub attachment URL on its own line — upload the file in any issue or pull request comment to get one. A relative link to an MP4 inside the repository does not play.
Why is my GIF so big?
Size grows with width × height × frames. Halve the width and the file shrinks about four times; go from 15 to 10 fps and it shrinks by a third. If it is still large, the clip is too long or the content changes too much for GIF — use an MP4 instead.
GIF or MP4 for a pull request?
MP4. GitHub plays it inline, it is many times smaller than a GIF of the same clip, and it keeps full colour.
Do these tools upload my recording?
No. Both the video compressor and the video to GIF converter decode and encode in your browser. Nothing leaves the tab, which matters for recordings of unreleased work.