How to enable provider caching when using Terragrunt

Last updated: July 14, 2025

When working with Terragrunt in Spacelift, you can enable provider caching to improve performance by preventing repeated downloads of provider binaries. Here's how to set it up correctly:

Prerequisites

Ensure you have:

  • A configured worker pool with binariesCacheVolume

  • Access to modify contexts in your Spacelift environment

Setting Up Provider Caching

To enable Terragrunt provider caching, you need to:

  1. Set the environment variable TERRAGRUNT_PROVIDER_CACHE=1 in your context and attach it to your stack.

    Note: The newer TG_PROVIDER_CACHE variable is not supported. Use TERRAGRUNT_PROVIDER_CACHE instead.

  2. For standard Terraform provider caching (non run-all stacks), you can also use the TF_PLUGIN_CACHE_DIR environment variable to specify where provider binaries should be stored.

Important Considerations

Keep in mind these key points:

  • The binariesCacheVolume in worker pools only caches core binaries (Terraform, Terragrunt, OpenTofu, kubectl) - it does not cache Terraform providers.

  • Provider binaries need their own dedicated storage space separate from the node's ephemeral storage.

  • You can verify if caching is working by checking the contents of your cache directory:

    ls -lah /mnt/ebs/terragrunt-cache

Troubleshooting

If provider caching isn't working:

  1. Verify the TERRAGRUNT_PROVIDER_CACHE environment variable is set correctly in your context

  2. Check if providers are being re-downloaded in each run by reviewing the logs

  3. Monitor disk usage with df -h to ensure you have sufficient storage space

  4. Ensure your cache directory is properly mounted and accessible

For more information about worker pools and binary caching, see the Spacelift Binaries Cache documentation.