How to Push Large Files to GitHub Without Errors (Using Git LFS)

Have you ever tried to git add or git push a large file to GitHub and hit an error like:

error: GH001: Large files detected. You may want to try Git Large File Storage – https://git-lfs.github.com.
fatal: The remote end hung up unexpectedly

You're not alone. By default, GitHub limits files to 100 MB, and large binary files can easily exceed that. But don’t worry — the solution is simple: Git LFS.

In this guide, you’ll learn how to push large files to GitHub safely and correctly using Git Large File Storage.

---

🚫 Why Large Files Break GitHub

GitHub (like many Git providers) limits:

• Individual files to 100 MB
• Repositories to 1 GB recommended, 5 GB max
• LFS usage to 1 GB of storage and 1 GB/month bandwidth (on free plans)

Large files slow down your repo and waste bandwidth. That’s why GitHub recommends using Git LFS.

---

✅ What is Git LFS?

Git Large File Storage (Git LFS) replaces large files (e.g., .zip, .mp4, .psd) in your repo with tiny pointer files and stores the actual content elsewhere. It keeps your repo fast and clean.

---

🚀 How to Use Git LFS on GitHub

🔧 1. Install Git LFS

macOS:

brew install git-lfs

Ubuntu/Debian:

sudo apt install git-lfs

Windows:

Download: https://git-lfs.github.com

---

🧰 2. Initialize Git LFS (once per machine)

git lfs install

---

📂 3. Track File Types You Want to Store with LFS

Before adding files, tell Git which file types to track:

git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "*.psd"

This updates or creates a .gitattributes file — make sure to commit it!

---

📥 4. Add and Commit Files

git add .gitattributes
git add big-video.mp4
git commit -m "Add large video using Git LFS"

---

☁️ 5. Push to GitHub

git push origin main

GitHub will now handle your large file through the LFS system.

---

🛠 Fix: Already Added File Without LFS?

If you already added a file without LFS, Git won’t retroactively fix it. You must:

git rm --cached bigfile.mp4
git lfs track "*.mp4"
git add .gitattributes
git add bigfile.mp4
git commit -m "Re-add file using Git LFS"
git push origin main

---

📊 GitHub LFS Limits (Free Plan)

Feature	Limit
File size (non-LFS)	Max 100 MB
File size (with LFS)	Up to 2 GB per file
LFS storage	1 GB total
LFS bandwidth	1 GB/month

🔁 Need more? GitHub lets you purchase extra LFS data.

---

🧪 Bonus: Does This Work on GitLab Too?

Yes, Git LFS also works on GitLab, Bitbucket, and others. But unlike GitHub, GitLab may require you to manually enable LFS in project settings.

This guide is written with GitHub in mind, but applies generally to all Git LFS-supported platforms.

---

💡 Pro Tips

• Always commit .gitattributes after tracking new types
• Use .gitattributes to enforce consistent LFS usage across your team
• Run git lfs status to check if files are being tracked correctly
• Clean up unused LFS objects with git lfs prune

---

🔚 Conclusion

Large files and Git don’t mix well — but with Git LFS, you can keep your repo fast and your files safely stored. Whether you’re versioning videos, design files, or data archives, Git LFS is the best way to stay under GitHub’s limits.

#Git #GitHub #GitLFS #DevTips #WebDevelopment #Programming #VersionControl #CodeTips #OpenSource #SoftwareEngineering #DeveloperTools