When GitHub says your file is too large

GitHub does not have one file size limit. It has three, they apply at different moments, and only one of them actually blocks you. Which error you got tells you which.

The current thresholds and their source are here.

The three thresholds

Threshold	Value	What happens
Browser upload	25 MiB	Refused outright by the web interface
Push warning	50 MiB	Push succeeds, Git warns you
Hard block	100 MiB	Push rejected by the server

So a 60MB file can be committed and pushed — you will get a warning and it will go through. A 120MB file cannot, and no amount of retrying changes that.

And a 30MB file cannot be added through the website at all, even though pushing it from the command line would work fine. That asymmetry is the single most confusing thing here: the file is not too large for the repository, only too large for the upload box.

MiB, not MB — and GitHub is right about it

GitHub is one of the few platforms that states its unit precisely, and it says MiB:

• 25 MiB = 26,214,400 bytes
• 50 MiB = 52,428,800 bytes
• 100 MiB = 104,857,600 bytes

That gives you about 4.9% more headroom than the decimal reading. It is not much, but if you are compressing a file to fit, aiming at the decimal number — 25,000,000 bytes rather than 26,214,400 — is safely under either interpretation and costs almost nothing. Why the two units exist and why nearly everyone conflates them.

The one that really hurts: history

This is the part that turns a small mistake into an afternoon.

The 100 MiB block applies to the file in your commit history, not to the file in your working tree. If you committed a 150MB file and then deleted it in a later commit, the blob is still in the history and the push is still rejected.

Deleting the file does not fix it. You have to rewrite the history to remove the blob — git filter-repo is the current recommended tool — and if the commit has already been pushed and others have pulled it, rewriting is disruptive.

So check before you commit, not after. A 200MB video dropped into a repository is cheap to avoid and expensive to undo.

What to do, by what you are adding

A video, GIF or screen recording for a README

The most common case, and compression is the right answer. A demo clip does not need to be 1080p60 at 12 Mbps — it is going to be played in a 700-pixel-wide column on a README page.

Target 720p, trim it to the thirty seconds that show the thing, and 25MB is generous. What fits in a given size is arithmetic: 25MB over 30 seconds is 6.6 Mbps, which is far more than a 720p screen recording needs.

Alternatively: upload the video by dragging it into an issue or pull request comment. GitHub hosts it on its own CDN and gives you a URL you can reference, which keeps the binary out of the repository entirely. That is usually the better engineering answer — a repository is for source, and a 25MB video in Git history is paid for by everyone who clones it, forever.

Screenshots

Should never approach these limits. A 4MB full-screen PNG in a repository is a sign it was not cropped — cropping and scaling a retina screenshot takes it to a few hundred kilobytes losslessly.

A dataset, model weights or a build artifact

Compression will not save you and should not. These belong in Git LFS, in a release asset, or in object storage — not in the repository.

Git LFS stores a small pointer in Git and the real bytes elsewhere, which is the correct shape for large binaries. Note that release assets and LFS have their own plan-dependent size limits, so check yours rather than assuming.

A PDF — documentation, a paper, a spec

Usually compressible by a lot, and usually losslessly. If the text selects, a structural rewrite frequently takes 30–70% off with nothing lost. Which case you are in takes five seconds to check.

The quick decision

Is it source code, text, or config?
  -> It is not the problem. Something else in the commit is.

Is it a demo video or GIF?
  -> Compress to 720p and trim it. Or host it in an
     issue comment and link to it.

Is it a screenshot?
  -> Crop it. Halve the dimensions if retina. Done.

Is it a dataset, binary, or model?
  -> Git LFS or a release asset. Do not compress it in.

Did you already commit it?
  -> Check whether it is in history before pushing again.
     Deleting the file is not enough.

Compressing without uploading, which matters here

If the file you need under 25MB is a screen recording of an internal tool, a demo of an unreleased product, or a dataset with real customer data in it, sending it to a web compressor to be processed on someone else's server is the wrong move regardless of how convenient it is.

Compress a video to 25MB, to 50MB or to 100MB runs the encode in your browser using your own machine's hardware encoder. Nothing is uploaded, there is no account, and the output is measured against the target before you get it — so "under 25MB" means it weighed under 25MB.

FAQ

What is GitHub's file size limit?

Three limits, depending on route. Files over 25 MiB cannot be added through the web interface. Files over 50 MiB generate a warning when pushed with Git but succeed. Files over 100 MiB are rejected by the server outright. Note that these are MiB — 100 MiB is 104,857,600 bytes, not 100,000,000.

Why is GitHub still rejecting my push after I deleted the large file?

Because the file is still in your commit history. The 100 MiB block applies to blobs in the commits being pushed, not to the current state of your working tree, so deleting the file in a later commit does not help. You need to rewrite history to remove the blob — git filter-repo is the recommended tool — which is disruptive if the commits have already been shared.

How do I add a demo video to a GitHub README?

Drag the video into an issue or pull request comment. GitHub uploads it to its own CDN and returns a URL you can reference from the README, which keeps the binary out of the repository entirely. If it must live in the repo, compress it to 720p, trim it to the part that demonstrates something, and keep it well under 25 MiB.

Should I use Git LFS instead of compressing?

For datasets, model weights, binary assets and anything that will be revised repeatedly, yes — LFS is the right shape for those and compression only delays the problem. For a demo video or a screenshot, compression is the better answer, because those are usually large only because nobody trimmed them, and LFS adds a dependency for every person who clones the repository.