Git LFS: How to Push Large Files to Git Repo

Large file management has traditionally been a challenge in Git, especially in projects that involve high-resolution media, large datasets, or compiled binaries.

Git Large File Storage (Git LFS) is a tool commonly used to overcome these challenges, as it was developed to solve Git's inefficiency in handling large or frequently changing binary files.

In this article, you will learn how Git LFS works and when it is the right solution for your version control needs.

Prerequisites

• Git installed (install Git on Windows, Mac, or Ubuntu).
• A Git repository.
• A user account with root/administrator privileges.

What Is Git LFS?

Git Large File Storage (Git LFS) is an open-source Git extension that optimizes how large files and binary assets are stored and retrieved. It offloads large files, such as media assets, datasets, or compiled binaries, into a separate storage system.

Instead of embedding bulky content directly in your Git history, LFS stores lightweight pointers within the repository and manages the actual file data elsewhere. This strategy keeps the Git repository lean, speeds up cloning and fetching operations, and facilitates collaboration without increasing version history size.

From a user's perspective, Git LFS integrates transparently into the standard Git workflow. After installing the LFS client, users configure which file types to track and continue to use Git normally. Under the hood, Git LFS intercepts interactions with files designated as large, swapping in pointers in your repository and handling the transfer of the real content to and from an LFS server only when you need it.

How Does Git LFS Work?

When you add a tracked file to Git, Git LFS replaces its full contents with a small pointer file and caches the actual data locally. Pushing a commit causes the LFS client to upload any new large-file data from the local cache to the remote LFS store associated with the repository.

On the other hand, when you checkout a commit, Git LFS checks for pointers and restores the files from the local cache. If the files are missing, it fetches them from the remote store on demand.

Since pointer files are very small, operations like git clone and git pull only retrieve the versions of large files you check out, rather than every revision that has ever existed. The working directory always shows the real file content, never the pointers.

For Git LFS to work, you need a Git host that supports LFS (for example, Bitbucket Cloud, GitHub, or a self-hosted LFS server) and the Git LFS client or a GUI tool with LFS support.

How to Install Git LFS?

The sections below outline the steps for installing the Git LFS client necessary for Git LFS to work. Depending on your operating system, refer to the relevant section.

Install Git LFS on Windows

Follow the steps below to install the Git LFS client on Windows:

1. Open a web browser and navigate to the official Git LFS website. Click the Download button and wait for the installer to finish downloading.

2. Double-click the downloaded file to run the Git LFS setup wizard.

3. Accept the license agreement and click Next to move on to the next step.

4. The next step is to choose the installation directory. Keep the default one unless you specifically need to change it, and click Next to start the installation.

5. Once the installation completes, click Finish to exit the installer.

6. Finally, open Git Bash and initialize Git LFS with the following command:

git lfs install

The output should state that Git LFS has been initialized, which means that the installation was successful.

Install Git LFS on Linux

The Git LFS client is available on Linux through the packagecloud repository. Follow the steps below to add the repository and install the client:

1. The packagecloud repository contains Git LFS packages for many Linux distributions. Depending on which Linux distribution you are using, run the appropriate command below to add the repository to your system:

For APT/DEB systems (Ubuntu, Debian, etc.), use:

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash

For YUM/RPM systems (RHEL, CentOS, Fedora), use:

curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.rpm.sh | sudo bash

2. Once you have added the repository, refresh the APT/DEB system package index with the new information. Run the command:

sudo apt update

3. Install the Git LFS client with the following command:

For APT/DEB systems, use:

sudo apt install git-lfs

For YUM/RPM systems, use:

sudo yum install git-lfs

Or, if you are using the dnf package manager, run:

sudo dnf install git-lfs

4. After installation, run the following command to initialize Git LFS in your system:

git lfs install

Install Git LFS on macOS

Git Large File Storage (Git LFS) is available on macOS through Homebrew, the most popular package manager for macOS. Follow the steps below to install it:

1. If you don't have it installed, run the following command in the Terminal to install Homebrew on macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Once Homebrew is installed, add Git LFS to your system with:

brew install git-lfs

3. After installation, initialize Git LFS with:

git lfs install

How to Use Git LFS?

Once you install Git LFS, associate it with the large file extensions in your repository that you want it to manage.

Follow the steps below to start using Git LFS:

1. Open Git Bash and use the cd command to navigate to an existing repository you want to manage with Git LFS.

2. Use the syntax below to associate a file type in your repository with Git LFS:

git lfs track [file_extension]

For example:

git lfs track .psd

The command above tracks .psd files and automatically uploads them to Git LFS. It also amends your repository's .gitattributes file and associates large files with Git LFS.

3. When you finish adding the file types you want to associate with Git LFS, commit your local .gitattributes file into your repository to ensure everyone who clones the repository automatically gets the same LFS rules.

Use the commands below to track and commit the .gitattributes file:

git add .gitattributes

git commit -m "Configure Git LFS to track PSD files"

4. Start tracking a file that has the extension you have associated with Git LFS:

git add [file_name]

For example:

git add example.psd

5. Commit and push the file to the remote repository:

git commit -m "Added a large file"

git push

The upload should be much faster, and Git no longer warns you that the file exceeds the recommended maximum of 50 MB.

Git LFS Drawbacks

While Git LFS helps manage large binary files in Git repositories, it introduces several important limitations that may impact team workflows and scalability.

Consider the following key points before you start using Git LFS:

• Setup and maintenance overhead. Each team member and build server must install and configure Git LFS individually. Every repository requires manual setup to track specific file types, commit tracking rules, and maintain consistency across environments, which creates extra work for developers and sysadmins.
• Performance limitations at scale. Cloning or migrating repositories with large or numerous LFS-tracked files can significantly slow down operations. Teams have reported multi-hour delays when working with repos that have extensive binary histories or large datasets.
• Storage quotas and added costs. Platforms like GitHub and Bitbucket charge separately for LFS storage and bandwidth. Free tiers are usually quickly exhausted, which leads to unexpected fees or download throttling, especially on projects with large or frequently updated media assets.
• Poor integration for non-developers. Git LFS is a CLI tool with limited support in visual software like game engines or design apps. This makes it harder for artists and designers to adopt, especially when managing asset versions or understanding LFS pointer files.
• Repository portability and offline issues. LFS files are not included in ZIP archives or mirrored automatically in forks. Without fetching all LFS objects, users cannot view historical versions offline or use the repo fully in disconnected environments.

Git LFS Alternatives

If Git LFS does not fit your needs, this section provides several other tools and services to consider, each with its own strengths and limitations:

• git-annex. Manages large files via symlinks and a separate key-value store. Offers encryption, multi-remote syncing, and excellent data integrity. However, the learning curve and reliance on command-line workflows can be steep for newcomers.
• Perforce Helix Core. An enterprise-grade version control system built for large binary assets. Delivers high performance, fine-grained access control, and seamless branching in studios handling huge game or media projects. The trade-off is complexity in setup and licensing costs.
• Mercurial Largefiles extension. Provides Git-LFS-style functionality in Mercurial repos, tracking large files outside the main history for lighter clones. It integrates smoothly with Mercurial workflows but has far fewer adopters and community resources than Git LFS.
• Plastic SCM (Unity version control). Designed around graphical assets and game-engine pipelines, Plastic SCM natively handles large files and offers visual branch visualization. It is not open source and uses a centralized server model, but its GUI approach is valued among studios.
• AWS CodeCommit. A fully managed Git service with built-in support for large files and scalable storage. It includes tight AWS integration (IAM, CodePipeline), no separate LFS quotas, and high availability. However, it is tied to AWS infrastructure and pricing.
• DVC (Data Version Control). Tailored for machine learning and data-centric projects, DVC tracks models and datasets alongside code. It stores large files in external object stores (S3, Azure, GCS) and integrates with Git, offering reproducibility and pipeline versioning. For teams not working on ML, its features can be more complex than needed.

Each alternative still relies on some form of command-line usage and may lack deep integration with art or design applications. Choosing the right tool depends on your team's workflow, budget, and the types of files you need to version.

Conclusion

This article explained what Git LFS is, how to install it, and the basis for using this essential tool for managing large files in Git repositories without compromising performance or exceeding size limits. While Git LFS does have some limitations, it remains a widely supported and practical solution for large file management across platforms.

Next, learn the difference between Git and GitHub, or refer to our beginner's guide to learn how to use Git.