GitHub File Size Limit: Keep README Media and Repo Images Small

GitHub blocks any file over 100 MiB and warns above 50 MiB. Uploading through the browser caps a file at 25 MiB, and attachments to issues and comments have their own, smaller caps. Each number below comes from GitHub’s documentation, read 11 October 2026.

Note the units. The push limits are written in MiB (1,048,576 bytes) and the attachment limits in MB, as GitHub prints them. A 100 MiB file is about 104.9 million bytes, so a tool that reports in decimal megabytes will show a larger number for the same file.

What is the GitHub 100 MB limit, and what does it cover?

The 100 MiB block applies to each file, not the repository total. Hitting it means a single file is too large; Git LFS is GitHub’s route for anything bigger, with per-file caps from 2 GB to 5 GB depending on plan.

A README rarely comes near the GitHub file size limit, and the real cost is quieter. Say a 3 MB PNG hero is committed in four versions: that is 12 MB of history that every clone downloads. If the file is an image, the fix is cheaper than LFS: make it smaller before it is committed. If it is a data file or a build artifact, compression will not help; keep it out of the repo or use LFS.

Images affect repo size permanently, because git keeps every committed version. Deleting a file in a new commit does not shrink the clone; only rewriting history does. Compress first, commit once.

We measured this in our git commit guide. In a test repository, three PNG hero exports took the pack to 8.34 MiB; deleting the PNG and adding a WebP took it to 8.51 MiB, slightly larger. Rewriting history with git-filter-repo brought it to 173.49 KiB, but every remaining commit hash changed and everyone had to re-clone. That is why shrinking images before the commit beats cleaning up after it. The web developer image guide covers the same habit for site assets, and documentation screenshots applies it to docs.

Resize to the width the README displays, then set quality. A 3200 px Retina capture shown in a column a fraction of that wide carries pixels nobody sees. The quality numbers below are starting points we chose, not measured thresholds; check every output.

Smol has no lossless image mode: it always re-encodes. If you need pixel-identical PNGs, use the ImageOptim head-to-head to decide. Smol’s own figure was 69.2% smaller PNGs at default quality 75, from 24 small test photos; see the benchmark for conditions. Flat UI screenshots behave differently from photos, so measure your own.

1. 1

   Collect the assets outside the repo

   Put new screenshots, GIFs and clips in a scratch folder. Originals stay untouched by default.

2. 2

   Drag the folder into Smol

   Mixed batches work, so images and a clip can go in together.

3. 3

   Set size and quality from the table above

   Maximum dimension 1600 for images, quality 75, then run the batch.

4. 4

   Check the largest output

   Smol sets quality and pixels, not bytes, so confirm each file is under the cap it needs to meet.

5. 5

   Copy the _compressed files into the repo

   Commit those, and reference them with a relative path.

GitHub’s formatting guide says to use relative links instead of absolute links for images in your repository. Compress the file you link, not a copy elsewhere. A Finder Quick Action makes it a right click.

Keep a README GIF under 10 MB if it will ever be attached to an issue, since that is the documented image and GIF cap, and aim far lower for README load time. GitHub publishes no ideal README GIF size in the pages above.

GIF is an inefficient format for motion. Smol cannot convert an animated GIF, so record the demo as video and compress that, or use the method in our GIF to MP4 guide. GitHub lists MP4, MOV and WebM as supported, and says codec support is browser specific with H.264 recommended for greatest compatibility. So choose MP4 with H.264, not H.265, for anything you share. See H.265 vs H.264 for the trade-off.

Drag an MP4, MOV or WebM into the comment box. The file must be 10 MB or less on a free plan or 100 MB on a paid plan, per GitHub’s attaching files page.

A screen recording of a bug is usually long and sharp. In Smol, choose MP4 with H.264, the Web quality label, drop the resolution, and remove the audio unless the bug is audible. Then check the size. Our screen recording guide has the details, and the screen recordings for support page covers sharing them. Smol cannot target a byte count for video, so if the clip is still over, trim it or lower the quality again.

The sips command is the free built-in route. For a Linux CI step, use an image library in the build or the Smol API.

• You need pixel-identical PNGs. Smol has no lossless mode; ImageOptim is the answer there.
• Your repo builds on Linux CI and images must be optimized in the pipeline. Smol is a Mac app.
• The file is a binary, dataset or archive over 100 MiB. Image compression does not apply; use Git LFS.
• You need SVG. Smol does not write or optimize SVG.
• The bloat is already in history. Compressing now does not shrink existing clones; that takes a history rewrite.

Do you have a team?

Solo is $29 once for one Mac. Team is $49 once for three Macs, and Enterprise is $20 a seat for 5 to 500 seats. Presets live on each Mac, so write your README settings down in CONTRIBUTING and recreate them. See pricing.