UtilityNest
GitHub logo

GitHub file size limits

Files added through the GitHub website must be under 25 MiB. Pushes from Git warn at 50 MiB and block files over 100 MiB; use Git LFS for anything larger.

25 MB Checked 2026-11-08
Or try:

The limits

WhatLimit
Upload in the browser25 MiB per file
Git pushPer file.Warning at 50 MiB, blocked at 100 MiB
Releases2 GiB per asset
RepositoryPushes are capped at 2 GB.Ideally under 1 GB, strongly recommended under 5 GB

Which GitHub limit applies depends on how the file arrives

GitHub has no single upload limit. The number you hit depends on the route the file takes into GitHub, and the routes are very different:

  • Add file, Upload files in the browser: up to 25 MiB per file, and up to 100 files at once.
  • git push from the command line: Git warns at 50 MiB, and GitHub blocks any file larger than 100 MiB. A single push is also capped at 2 GB.
  • Git Large File Storage: the per-file maximum depends on the plan, 2 GB on GitHub Free and Pro, 4 GB on Team and 5 GB on Enterprise Cloud.
  • Release assets: up to 1000 files per release, each under 2 GiB, with no limit on the total size or the download bandwidth.
  • Issues, pull requests and discussions: images and GIFs up to 10 MB, videos up to 10 MB on free plans and 100 MB on paid plans, and other files up to 25 MB.

Repository size is guidance, not a wall

GitHub asks that repositories stay small, ideally under 1 GB, and strongly recommends staying under 5 GB. Its repository limits page lists 10 GB of on-disk size (the compressed .git folder) as a recommended maximum. These are health thresholds rather than a hard stop: a repository that strains GitHub's systems may get an email from GitHub Support asking for changes. The hard numbers are per object and per push, which GitHub enforces at 100 MB and 2 GB.

This matters because Git keeps every version of every file forever. A 40 MB video committed and then deleted still sits in history, and every clone downloads it again.

Images in a README are where size quietly hurts

README screenshots never trip the 25 MiB browser limit, but they are downloaded by every visitor and stored in every clone. GitHub also says formatted previews of files such as Markdown are attempted when the file is small, generally under 2 MB. A few habits keep a project page quick:

  • Convert large PNG screenshots with /convert-to-webp. WebP displays in every current browser.
  • If a screenshot must stay PNG, run it through /compress-image.
  • Crop to the part that matters with /crop-image instead of posting a full 4K desktop.
  • Animated demos: /video-to-gif makes large files fast; a short MP4 uploaded into an issue or README comment is often much smaller than the same GIF.
  • Design files, videos and installers belong in a release or in Git LFS rather than in normal commits.

If a push was already rejected

If the big file is in the last commit you have not pushed yet, GitHub's guide is to remove it with git rm --cached, amend the commit with git commit --amend -CHEAD, and push again. A new commit that deletes the file is not enough, because the file is still in the earlier commit. If it was added further back, GitHub recommends git filter-repo to rewrite history. Make a backup copy outside the repository first, since these steps permanently remove the file.

Our test: a full-screen PNG screenshot converted for a README

We made a 2560 x 1600 PNG of a code editor layout with a sidebar, text and colored panels (already saved with PNG optimization). We ran it through /convert-to-webp in headless Chromium at the Balanced quality of 80, with no resizing.

File size434.3 KB (444,755 bytes)291.6 KB (298,572 bytes)
Pixels2560 x 16002560 x 1600
Saved33%
TimeUnder 1 second after clicking Convert

A third off a single image is small, but a README with eight such screenshots saves over a megabyte for every visitor. Turning on Shrink large images at 1920 px would save more, and a README column never shows 2560 px anyway.

Error messages and what to do

The browser upload refuses a file

Files added through the web interface are limited to 25 MiB each.

Push it with Git from the command line (up to 100 MiB), or attach it to a release.

A push is rejected and names a file over 100 MiB

GitHub blocks files larger than 100 MiB in regular Git.

Remove the file from the commit history, then track it with Git LFS or publish it as a release asset.

Git prints a warning about a large file, but the push succeeds

The file is over 50 MiB. GitHub accepts it but suggests removing it.

Consider moving it to Git LFS before the repository grows.

A video will not attach to an issue

Videos are limited to 10 MB on free plans and 100 MB on paid plans.

Compress it with /compress-video, or trim it with /trim-video.

Questions people ask

Is MiB the same as MB here?

Not quite. GitHub states the browser and push limits in MiB, where 1 MiB is 1,048,576 bytes, so 25 MiB is about 26.2 million bytes.

Do release assets count toward repository size?

Releases are GitHub's recommended way to distribute large binaries instead of tracking them in the repository, and GitHub does not limit the total size of a release.

Can I upload a whole folder of 300 images in the browser?

GitHub allows up to 100 files at a time through the browser, so split it into batches or push with Git.

What is the maximum Git LFS file on a free account?

2 GB per file on GitHub Free.

Also checked for this guide

Make your file fit

Each button opens the tool already set to this limit. Files are processed in your browser.

Good to know

  • Screenshots in README files should be compressed PNG or WebP under 500 KB so pages load fast.
  • Design files and videos belong in Releases or Git LFS, not in commits.

Sources

More cloud and work tools limits