GitHub File Size Limit: 25MB, 50MB, 100MB and How to Push Large Files
GitHub File Size Limit: The Short Answer
The GitHub file size limit depends on how the file gets there:
- Pushed with Git: warning above 50MiB, blocked above 100MiB per file.
- Uploaded in the browser: 25MiB per file.
- Tracked with Git LFS: up to 2GB per file on Free and Pro plans (4GB on Team, 5GB on Enterprise Cloud).
- Attached to a release: up to 2GiB per file, with no total size or bandwidth limit.
The 100MB block is the one that ruins your afternoon, because it's enforced at push time, after the file is already baked into a commit. Deleting the file and committing again doesn't help. The rest of this guide covers every limit, how to fix the rejected push, and how to keep large files out of your repo in the first place.
Every GitHub Size Limit in One Table
| Where | Limit | What happens |
|---|---|---|
| File pushed with Git | 50MiB | Push succeeds with a warning |
| File pushed with Git | 100MiB | Push rejected (GH001) |
| File uploaded on github.com | 25MiB | Upload refused |
| Single push | 2GB | Push rejected; push history in smaller batches |
| Repository | <1GB ideal, <5GB strongly recommended | Slow clones; GitHub may contact you |
| Git LFS file (Free / Pro) | 2GB | LFS upload refused |
| Git LFS file (Team / Enterprise Cloud) | 4GB / 5GB | LFS upload refused |
| Git LFS quota (Free / Pro) | 10GiB storage + 10GiB bandwidth per month | LFS stops without a payment method |
| Release asset | 2GiB per file | No total size or bandwidth cap |
| Issue / PR image or GIF | 10MB | Upload refused |
| Issue / PR video | 10MB (free plan) / 100MB (paid plan) | Upload refused |
| Other issue / PR attachments | 25MB | Upload refused |
| GitHub Pages site | 1GB published size, ~100GB/month soft bandwidth | Build or usage warnings |
These are GitHub.com limits. GitHub Enterprise Server administrators can set their own.
What the 100MB Error Looks Like
remote: error: File assets/demo.mp4 is 142.51 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
To github.com:you/project.git
! [remote rejected] main -> main (pre-receive hook declined)
GitHub checks every commit in the push, not just the latest state of your files. If demo.mp4 was committed three commits ago and deleted in the last one, the push is still rejected, because the big file still exists in history.
How to Fix "GH001: Large Files Detected"
Back up the file somewhere outside the repo before you start, then pick the case that matches.
Case 1: The large file is only in your last commit
git rm --cached assets/demo.mp4
echo "assets/demo.mp4" >> .gitignore
git add .gitignore
git commit --amend --no-edit
git push
--cached removes the file from Git but leaves it on your disk.
Case 2: The large file is in older commits
You need to rewrite history to remove it. The recommended tool is git filter-repo (brew install git-filter-repo on a Mac):
git filter-repo --path assets/demo.mp4 --invert-paths
Then re-add your remote if filter-repo removed it, and push. If the branch already exists on GitHub, you'll need git push --force-with-lease, and anyone else working on the repo should re-clone. Only rewrite shared history after telling your collaborators.
Case 3: You actually want the file in the repo
Move it into Git LFS, including in past commits:
git lfs install
git lfs migrate import --include="*.mp4" --everything
git push --force-with-lease
migrate import rewrites the matching files in history into LFS pointers, so the 100MB check passes.
Git LFS: How It Works and What It Costs
Git LFS replaces large files in your repository with small text pointer files. The real content lives on GitHub's LFS storage and downloads when someone checks out the commit that needs it.
Setting it up for new files:
git lfs install # once per machine
git lfs track "*.psd" "*.mp4" # writes rules to .gitattributes
git add .gitattributes
git add design/hero.psd
git commit -m "Track design files with LFS"
git push
Things that catch people out:
- The quota counts downloads. Every clone, every CI run with
lfs: true, and every fork's download counts against the repository owner's bandwidth. A 500MB set of LFS files pulled by CI 20 times a month uses the full free 10GiB. - Forks inherit the cost. Pushes to a fork's LFS storage count against the parent repository's owner.
- Removing a file from LFS doesn't free its storage. Every version you pushed keeps counting until the LFS objects themselves are deleted, which is far more work than deleting a file.
- LFS is version control for big files, not a CDN. If nobody needs history for the file, it probably doesn't belong in LFS.
Better Homes for Large Files
| File type | Better option |
|---|---|
| Installers, binaries, compiled builds | GitHub Releases (2GiB per file, no bandwidth cap) |
| Datasets and model weights | Releases, object storage (S3, R2), or a dataset host |
| Design source files (PSD, Sketch, Figma exports) | Git LFS or a shared drive |
| Demo videos and screen recordings | Compress them, then use README video embeds or Releases |
| Screenshots and docs images | Compress them; they rarely need to be large |
| Source code archives | GitHub generates Source code (tar.gz) and .zip for every release automatically |
Those automatic source archives are standard tarballs. If someone asks how to open one, point them at how to extract tar.gz files.
The Easiest Fix: Make the File Smaller
A lot of 100MB errors are caused by media: a demo video, a screen recording for docs, a folder of uncompressed screenshots, or a README GIF that grew to 40MB. Those files don't need to be that large.
- Demo videos: a 3-minute 4K screen recording can be 500MB or more. Re-encoded at 1080p with H.264 or HEVC, it's usually 20–40MB and looks the same in a README. See optimize video for web.
- README GIFs: GIF is a terrible video format. An 8MB GIF is often a 500KB MP4. GitHub renders uploaded videos in Markdown (drag the MP4 into an issue or pull request comment, then paste the generated link into your README), so converting GIF to MP4 is usually the best move. If it has to stay a GIF, compress the GIF to get under the 10MB attachment limit.
- Screenshots and docs images: PNG screenshots from a Retina display are often 2–5MB each. Lossless optimisation cuts that by half or more. See PNG optimizer and, for icons and diagrams, SVG optimizer.
Compresto does all three on a Mac: batch-compress videos, convert video to GIF (or shrink existing GIFs to a max width), and optimise PNG, JPEG, WebP, and SVG files, locally and with a target file size when you need to land under a specific limit like 10MB or 25MB.
Other File Size Limits Worth Knowing
GitHub isn't the only place that rejects large files. If you're sharing the same assets elsewhere:
FAQ
What is the GitHub file size limit?
100MiB per file pushed with Git (warning at 50MiB), 25MiB in the browser, and 2–5GB per file with Git LFS depending on plan.
How do I fix "GH001: Large files detected"?
Remove the file from every commit in the push: git commit --amend if it's only in the last commit, git filter-repo or git lfs migrate import if it's older.
What is the maximum repository size on GitHub?
No hard cap, but stay under 1GB ideally and 5GB at most. Single pushes over 2GB are rejected.
How much does Git LFS cost on GitHub?
10GiB storage and 10GiB monthly bandwidth free on Free and Pro; 250GiB of each on Team and Enterprise Cloud. Extra usage is billed.
What is the file size limit for GitHub releases?
2GiB per file, with no limit on total release size or bandwidth.
What is the size limit for images and videos in GitHub issues and READMEs?
10MB for images and GIFs, 10MB for videos on free plans (100MB on paid plans), 25MB for other files.
Bottom Line
GitHub's file size limit is 100MB per file, enforced on every commit in a push. Fix a rejected push by removing the file from history or moving it into LFS, put binaries in Releases, and shrink media before it ever reaches the repo.