Skip to main content

Compress GIF for GitHub README & PRs

Keep demo GIFs sharp and fast-loading in GitHub READMEs, pull requests, and issues. Stay under GitHub 10MB upload cap and 1MB social preview limit while keeping terminal and UI text readable.

Updated:

Drop GIFs here or choose files

Paste an HTTPS image URL

Prepare a GIF for your platform

Platform limits and recommended compression targets are different. Check the limit shown in your account before uploading.

GitHub

GitHub caps drag-and-drop issue and PR GIF attachments separately from repository social preview images.

  • Images and GIFs attached to issues, pull requests, and comments are capped at 10MB.
  • Repository social preview images (PNG, JPG, or GIF) must be under 1MB; 1280×640 pixels is recommended.
  • Avoid committing large GIFs directly into Git history; compress README demos to 1–2MB and host them via issue/PR uploads or release assets.

Last verified:

How to use this tool

  1. Drop your terminal or UI demo GIF into the tool (2MB target is preselected).
  2. Compress locally in your browser and inspect code/menu legibility.
  3. If text blurs, crop unused desktop space first instead of shrinking width.
  4. Drag the downloaded GIF into a GitHub issue/PR box to get a hosted URL, or automate with our API/MCP.

GitHub GIF limits: README, PRs, and Social Preview

GitHub enforces a 10MB cap for images and GIFs attached to issues, pull requests, and comments, and a stricter under-1MB cap for repository social preview cards (recommended 1280×640px).

1 — Issue and PR attachment up to 10MB with 1 to 2MB README target · 2 — Repository social preview 1280 by 640 under 1MB
1 — Issue/PR attachment (≤10MB cap; 1–2MB recommended for READMEs) · 2 — Repository social preview (1280×640px, <1MB)
GitHub locationOfficial limitBest practice
Issue / PR / Comment attachment10MB for images & GIFsKeep demos 1–3MB so reviewers load diffs fast.
README.md demo10MB if hosted via PR/Issue uploadAvoid committing big GIFs into git history; crop to active window.
Repository social previewUnder 1MB (1280×640px)Use static PNG/JPG or a minimal <1MB GIF.

Measured examples

Self-authored examples, processed with the same compression engine as this tool. Results vary with the source; these are not promises for your files.

Measurement data (JSON)
TargetOriginalActual size
Target: 1000 KB1,141,589 Bytes903,284 BytesTarget met
Cropped and shortened tutorial · Target: 1000 KB560,904 Bytes531,027 BytesTarget met

Target: 1000 KB

Original · 1,141,589 Bytes

Target: 1000 KB: Original

Output · 903,284 Bytes

Target: 1000 KB: Output

Dimensions: 640 × 360px
Frames: 40 · Duration: 4 seconds

Applied settings: 256 Maximum colors · Lossy level 20

Inspect detail

Original

Target: 1000 KB: Original

Output

Target: 1000 KB: Output

Cropped and shortened tutorial · Target: 1000 KB

Edited source · 560,904 Bytes

Cropped and shortened tutorial · Target: 1000 KB: Edited source

Output · 531,027 Bytes

Cropped and shortened tutorial · Target: 1000 KB: Output

Dimensions: 420 × 182px
Frames: 20 · Duration: 2 seconds

Applied settings: 256 Maximum colors · Lossy level 0

Edited source: 640 × 360px · 40 Frames · 4 seconds → 420 × 182px · 20 Frames · 2 seconds

Inspect detail

Original

Cropped and shortened tutorial · Target: 1000 KB: Original

Output

Cropped and shortened tutorial · Target: 1000 KB: Output

Why you should not commit large GIFs into Git history

Every time you commit or replace an uncompressed 8MB GIF inside your repository, Git permanently stores it in packfiles, slowing down every future git clone and CI checkout.

Instead, compress your demo to 1–2MB, drag it into a GitHub issue or draft PR comment to generate a hosted GitHub user-attachments URL, and paste that Markdown link into README.md.

  1. Crop recording to the active editor or terminal window
  2. Trim idle typing pauses with Trim GIF
  3. Compress to 1–2MB while preserving crisp UI text
  4. Upload via GitHub drag-and-drop or automate in CI with REST API

How to keep code and terminal text readable in a 2MB GIF

Terminal and IDE recordings compress surprisingly well because most pixels stay static between frames. Resizing a 1440px screen down to 600px destroys 12px monospace fonts; cropping tightly to a 720px window preserves pixel-sharp text at half the file size.

Frequently asked questions

What is the maximum GIF size for GitHub issues and PRs?

GitHub allows up to 10MB for images and GIFs attached to issues, pull requests, and comments.

Why is my GitHub README GIF not loading or timing out?

GitHub Camo image proxy can time out on oversized external GIFs. Keeping README GIFs under 2–5MB ensures reliable rendering.

Can I compress GIFs automatically in GitHub Actions?

Yes. CompressGIF offers a free tier REST API (500 monthly credits, no card required) and an MCP server so CI pipelines or agents can compress demo GIFs automatically.

Should I use MP4 instead of GIF in GitHub READMEs?

GitHub supports drag-and-drop MP4 videos (10MB free, 100MB paid) in issues, PRs, and READMEs. Use GIF when you need instant looping without video controls, or convert long recordings to MP4.