Git Large File Storage (LFS) All tiers All offerings
Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. The general recommendation is to not have Git repositories larger than 1 GB to preserve performance.
Your Git LFS client communicates with the GitLab server over HTTPS. It uses HTTP Basic authentication to authorize client requests. After the request is authorized, Git LFS client receives instructions on where to fetch or where to push the large file.
In the repository view, files tracked by Git LFS display an LFS badge next to the filename:
Configure your GitLab server for Git LFS All tiers Self-managed
To install Git LFS on your self-managed GitLab server, see GitLab Git Large File Storage (LFS) Administration.
Enable Git LFS for a project
Prerequisites:
- You must have at least the Developer role in the project.
To do this:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > General.
- Expand the Visibility, project features, permissions section.
- Turn on the Git Large File Storage (LFS) toggle.
- Select Save changes.
Install the Git LFS client locally
Install the Git LFS client appropriate for your operating system. GitLab requires version 1.0.1 or later of the Git LFS client.
Known limitations
- Git LFS v1 original API is not supported, because it was deprecated early in LFS development.
- When SSH is set as a remote, Git LFS objects still go through HTTPS.
- Any Git LFS request asks for HTTPS credentials, so we recommend a good Git credentials store.
- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must add the URL to Git configuration manually.
- Group wikis do not support Git LFS.
How LFS objects affect repository size
When you add an LFS object to a repository, GitLab:
- Creates an LFS object.
- Associates the LFS object with the repository.
- Queues a job to recalculate your project’s statistics, including storage size and LFS object storage. Your LFS object storage is the sum of the size of all LFS objects associated with the repository.
When your repository is forked, LFS objects from the upstream project are associated with the fork. When the fork is created, the LFS object storage for the fork is equal to the storage used by the upstream project. If new LFS objects are added to the fork, the total object storage changes for the fork, but not the upstream project.
If you create a merge request from the fork back to the upstream project, any new LFS objects in the fork become associated with the upstream project.
Using Git LFS
Let’s take a look at the workflow for checking large files into your Git repository with Git LFS. For example, if you want to upload a very large file and check it into your Git repository:
git clone git@gitlab.example.com:group/my-sample-project.git
cd my-sample-project
git lfs install # initialize the Git LFS project
git lfs track "*.iso" # select the file extensions that you want to treat as large files
After you mark a file extension for tracking as a LFS object you can use Git as usual without redoing the command to track a file with the same extension:
cp ~/tmp/debian.iso ./ # copy a large file into the current directory
git add . # add the large file to the project
git commit -am "Added Debian iso" # commit the file meta data
git push origin main # sync the git repo and large file to the GitLab server
Make sure that .gitattributes
is tracked by Git. Otherwise Git
LFS doesn’t work properly for people cloning the project:
git add .gitattributes
git commit -am "Added .gitattributes to capture LFS tracking"
git push origin main
Cloning the repository works the same as before. Git automatically detects the
LFS-tracked files and clones them via HTTP. If you performed the git clone
command with a SSH URL, you have to enter your GitLab credentials for HTTP
authentication.
git clone git@gitlab.example.com:group/my-sample-project.git
If you already cloned the repository and you want to get the latest LFS object that are on the remote repository, such as for a branch from origin:
git lfs fetch origin main
Make sure your files aren’t listed in .gitignore
, otherwise, they are ignored by Git
and are not pushed to the remote repository.
Migrate an existing repository to Git LFS
Read the documentation on how to migrate an existing Git repository with Git LFS.
Removing objects from LFS
To remove objects from LFS:
- Use
git filter-repo
to remove the objects from the repository. - Delete the relevant LFS lines for the objects you have removed from your
.gitattributes
file and commit those changes.
File Locking
See the documentation on File Locking.
LFS objects in project archives
-
Introduced support for including Git LFS blobs inside project source downloads in GitLab 13.5 with a flag named
include_lfs_blobs_in_archive
. Disabled by default. - Enabled on GitLab.com and self-managed in GitLab 13.6.
-
Generally available in GitLab 14.0. Feature flag
include_lfs_blobs_in_archive
removed.
Prior to GitLab 13.5, project source downloads would include Git LFS pointers instead of the actual objects. For example, LFS pointers look like the following:
version https://git-lfs.github.com/spec/v1
oid sha256:3ea5dd307f195f449f0e08234183b82e92c3d5f4cff11c2a6bb014f9e0de12aa
size 177735
In GitLab version 13.5 and later, these pointers are converted to the uploaded LFS object.
Technical details about how this works can be found in the development documentation for LFS.
Related topics
- Blog post: Getting started with Git LFS
- Git LFS developer information
- GitLab Git Large File Storage (LFS) Administration for self-managed instances
Troubleshooting
Encountered n
files that should have been pointers, but weren’t
This error indicates the files are expected to be tracked by LFS, but the repository is not tracking them as LFS. This issue can be one potential reason for this error: Files not tracked with LFS when uploaded through the web interface
To resolve the problem, migrate the affected file (or files) and push back to the repository:
-
Migrate the file to LFS:
git lfs migrate import --yes --no-rewrite "<your-file>"
-
Push back to your repository:
git push
-
Optional. Clean up your
.git
folder:git reflog expire --expire-unreachable=now --all git gc --prune=now
error: Repository or object not found
This error can occur for a few reasons, including:
- You don’t have permissions to access certain LFS object
Check if you have permissions to push to the project or fetch from the project.
- Project is not allowed to access the LFS object
LFS object you are trying to push to the project or fetch from the project is not available to the project anymore. Probably the object was removed from the server.
- Local Git repository is using deprecated LFS API
Invalid status for <url>
: 501
Git LFS logs the failures into a log file. To view this log file, while in project directory:
git lfs logs last
If the status error 501
is shown, it is because:
-
Git LFS is not enabled in project settings. Check your project settings and enable Git LFS.
-
Git LFS support is not enabled on the GitLab server. Check with your GitLab administrator why Git LFS is not enabled on the server. See LFS administration documentation for instructions on how to enable LFS support.
-
Git LFS client version is not supported by GitLab server. Check your Git LFS version with
git lfs version
. Check the Git configuration of the project for traces of deprecated API withgit lfs -l
. Ifbatch = false
is set in the configuration, remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported.
getsockopt: connection refused
If you push an LFS object to a project and receive an error like this, the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP:
Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused
This behavior is caused by Git LFS using HTTPS connections by default when a
lfsurl
is not set in the Git configuration.
To prevent this from happening, set the LFS URL in project Git configuration:
git config --add lfs.url "http://gitlab.example.com/group/my-sample-project.git/info/lfs"
Credentials are always required when pushing an object
Git LFS authenticates the user with HTTP Basic Authentication on every push for every object, so user HTTPS credentials are required.
By default, Git has support for remembering the credentials for each repository you use. For more information, see the official Git documentation.
For example, you can tell Git to remember the password for a period of time in which you expect to push the objects:
git config --global credential.helper 'cache --timeout=3600'
This remembers the credentials for an hour, after which Git operations require re-authentication.
If you are using OS X you can use osxkeychain
to store and encrypt your credentials.
For Windows, you can use wincred
or Microsoft’s Git Credential Manager for Windows.
More details about various methods of storing the user credentials can be found on Git Credential Storage documentation.
LFS objects are missing on push
GitLab checks files to detect LFS pointers on push. If LFS pointers are detected, GitLab tries to verify that those files already exist in LFS on GitLab.
Verify that LFS is installed locally and consider a manual push with git lfs push --all
.
If you are storing LFS files outside of GitLab you can disable LFS on the project by setting lfs_enabled: false
with the projects API.
Hosting LFS objects externally
It is possible to host LFS objects externally by setting a custom LFS URL with git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs
.
You might choose to do this if you are using an appliance like a Nexus Repository to store LFS data. If you choose to use an external LFS store, GitLab can’t verify LFS objects. Pushes then fail if you have GitLab LFS support enabled.
To stop push failure, LFS support can be disabled in the Project settings, which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS).
I/O timeout when pushing LFS objects
You might get an error that states:
LFS: Put "http://your-instance.com/root/project.git/gitlab-lfs/objects/cc29e205d04a4062d0fb131700e8bfc8e54c44d0176a8dca22f40b24ef26d325/15": read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout
error: failed to push some refs to 'ssh://your-instance.com:2222/root/project.git'
When network conditions are unstable, the Git LFS client might time out when trying to upload files if network conditions are unstable.
The workaround is to set the client activity timeout a higher value.
For example, to set the timeout to 60 seconds:
git config lfs.activitytimeout 60