How to Upload Large Files on GitHub: A Complete Guide

By default, GitHub limits file uploads to 100 MB per file in a repository. If you’re trying to upload datasets, videos, binaries, or other large assets, you may run into errors like:

fatal: the file 'your-file.zip' is too large

In this guide, you’ll learn how to upload large files to GitHub safely and efficiently, whether you’re working on a personal project or collaborating in a team.

Table of Contents

🚫 Why Large Files Are an Issue in GitHub

Git was designed to track code, not large binaries or media.
GitHub restricts individual file uploads to 100 MB.
Repositories over 1 GB may receive a warning from GitHub.
Large files slow down cloning, fetching, and history operations.

✅ Option 1: Use Git Large File Storage (Git LFS)

Git LFS is the official solution from GitHub for managing large files.

🔧 Step 1: Install Git LFS

# On macOS (with Homebrew)
brew install git-lfs

# On Windows or Linux
https://git-lfs.github.com

Then initialize LFS:

git lfs install

🔁 Step 2: Track Large Files

Specify file types or specific files to be managed by LFS:

git lfs track "*.psd"

Or:

git lfs track "bigfile.zip"

This creates a .gitattributes file to store tracking info.

📤 Step 3: Add, Commit, and Push

git add bigfile.zip
git commit -m "Add large file with Git LFS"
git push origin main

You may need to enable Git LFS for your GitHub repo.

✅ Option 2: Use GitHub Releases for Binary Files

If you don’t need the large file to be tracked in Git history, but simply want it available for download, you can attach it to a GitHub release.

🛠 Steps:

Create a new tag or release on GitHub
Click “Draft a new release”
Upload your large file (up to 2 GB)
Publish the release

Great for distributing binaries, builds, or final assets.

✅ Option 3: Use External Storage + Link

For files larger than 2 GB, or if you’re dealing with frequent updates, it’s better to host files externally and link them in your repo:

Amazon S3 or Google Cloud Storage
Dropbox or Google Drive
Azure Blob Storage
IPFS for decentralized hosting

You can include a README.md note with download instructions or a script to fetch the files.

⚠️ What Not to Do

❌ Don’t force push huge files directly
❌ Don’t track video/audio/images directly in Git
❌ Don’t ignore GitHub’s usage policies—they may disable your repo if you exceed limits

🧠 Best Practices

Use .gitignore to exclude build artifacts and non-source files.
Use git lfs track only for files that truly need versioning.
Keep your repository under 1 GB total, even with LFS.
Use releases or external storage for versioned deliverables.

🚀 Summary

Method	Max File Size	Versioned	Recommended For
GitHub Regular Upload	100 MB	✅	Small code, text files
Git LFS	2 GB per file	✅	Media, datasets, binaries
GitHub Releases	2 GB per file	❌	Distributable assets
External Hosting + Links	Unlimited	❌	Large backups, bulk storage