Large Media requirements and limitations

Netlify Large Media can be a powerful tool for your sites and apps, but because it's built on Git LFS, it fundamentally changes how your Git repository works, and how your files are handled on Netlify.

Make sure to review the following requirements and limitations before enabling Large Media on a site and repository.

Requirements

To enable Large Media on a site repository, or to connect to an existing Large-Media-enabled site for local development, you need the following:

  • A Netlify site connected with a Git repository for continuous deployment. If the repository is using Git LFS with another provider, visit our Community forum for guidance on migrating your files from other LFS providers.

  • A Netlify user login with access to the site settings, connected to your Git provider account. (This is true for every collaborator committing large media files to the site, unless they are using Netlify CMS.)

  • Git LFS version 2.5.1 or above, installed on your local machine. You can run git lfs version in your terminal to see if you have a valid version installed. If not, follow the installation instructions on the Git LFS website.

  • Netlify CLI version 2.6.4 or above. Refer to the CLI docs for information on installation, authentication, and linking your local repository clone to your Netlify site.

  • Netlify Large Media plugin for Netlify CLI. Run the following commands in your terminal to install the plugin:

    netlify plugins:install netlify-lm-plugin
    netlify lm:install
    

    After running these commands, you will be presented with a custom command to run in order to use Netlify Large Media in your shell. Copy and run this command.

Limitations

Different sites have different needs, and Netlify Large Media may not be the best solution for all situations. Make sure to review the following before enabling Large Media on a site and repository:

  • Files tracked with Netlify Large Media are tied to a specific site. This means that Deploy to Netlify buttons and repositories with multiple connected sites (such as monorepos) are not supported. Similarly, you cannot create a new site from a fork of a repository, though you can fork a Large-Media-enabled repository for the purpose of making contributions to be merged into the original repository.
  • Files tracked with Large Media are uploaded directly to the Netlify Large Media storage service on push, completely bypassing the site build. This saves build time, but also means that the files are not available to tools that process asset files during the build, such as Hugo's image processing or the gatsby-image plugin. Depending on your needs, you may be able to replace this functionality with Netlify's image transformation service.
  • Uploading tracked files to the Netlify Large Media storage service requires Git to have access to the /.netlify/large-media path on the connected site. This will not work with site-wide password protection, but will work with other forms of visitor access control, as long as you leave access open to the /.netlify/large-media path.
  • Netlify Large Media is not compatible with Netlify's built-in asset optimization. If you enable Netlify Large Media, you need to select Disable asset optimization in your site dashboard under Settings > Build & deploy > Post processing > Asset optimization.
  • Netlify Large Media is not suitable for streaming audio or video files. However, storing these assets for download should work well.

To stop service

Netlify Large Media's connection with Git LFS requires extra care when disabling the service or deleting a site with the service enabled.

Disable Large Media

Because Netlify Large Media and Git LFS change the way your files are saved, disabling Large Media requires assistance from Netlify Support.

Delete a site with Large Media enabled

When you configure a repository to use Git LFS and Large Media, your designated LFS-tracked files will no longer be stored in your repository on your Git provider. Instead, they will be stored in the Large Media store for your connected Netlify site. This means that if you delete that site, you will not be able to recover the files at your Git provider.

Don't forget to make a copy!

To avoid permanent file loss, always clone your entire repository locally before deleting a site with Large Media enabled.

To clone your entire repository with all branches and history, run the following command:

git clone --mirror YOUR_REPOSITORY_URL

Make sure your files have downloaded properly before deleting the connected site on Netlify.