When pushing to GitHub, you'll receive a warning message if you add a new file or update an existing file larger than 50MB, and will be blocked from pushing files larger than 100MB.

While Git is great for versioning and storing code, it has trouble with large files, as its architecture requires that there exist as much free space on disk as consumed space at all times. (e.g., if a repository is 1GB, Git requires 1GB of free space to be available.) Additionally, large files can increase clone and fetch times for other users of the repository.

If you regularly push large files to GitHub, you should evaluate your workflow to determine if it is truly necessary to keep those files under version control.

Files to keep in Git

  • Code files
  • Versioned assets, such as graphics
  • Large configuration files

Files to consider removing from Git

  • Database dumps
  • Log files

For more information on managing your repository's size, see "What is my disk quota?".

Push warnings and limits

50MB push warning

When pushing to GitHub, you'll receive a warning or error message if you either add a new file or update an existing file that is larger than 50 MB.

The warning will tell you which files are too large:

# remote: warning: Large files detected.
# remote: warning: File big_file is 55.00 MB; this is larger than GitHub's recommended maximum file size of 50 MB

The push with big_file is received and saved into the repository on GitHub, but you should consider removing the file and the commit entirely.

100MB push limit

If you push a file larger than 100MB to GitHub, Git will reject the push and tell you which file is too large:

# remote: warning: Large files detected.
# remote: error: File giant_file is 123.00 MB; this exceeds GitHub's file size limit of 100 MB

This push was rejected because of giant_file. The commits will not be saved into the repository on GitHub.

Removing the large file

Warning: The steps below will remove the file from the repository on your computer and GitHub. If the file is important, make a local backup copy in a directory outside the repository.

To fix the problem, you must completely remove the large file from Git on your computer and GitHub.

Removing the local file added with the most recent unpushed commit

If the file was added with your most recent commit, and you have not pushed to the remote repository, you can delete the file and amend the commit:

git rm --cached giant_file
# Stage our giant file for removal, but leave it on disk

git commit --amend -CHEAD
# Amend the previous commit with your change
# Simply making a new commit won't work, as you need
# to remove the file from the unpushed history as well

git push
# Push our rewritten, smaller commit

Removing the file added in an older commit

If the large file was added in an earlier commit, you will need to remove it from your repository history. The quickest way to do this is with The BFG (a faster, simpler alternative to git-filter-branch):

bfg --strip-blobs-bigger-than 50M
# Git history will be cleaned - files in your latest commit will *not* be touched

See The BFG's documentation for full usage and download instructions.