Skip to main content
In this lesson, we’ll dive into the download_dir attribute in Terragrunt. This setting lets you control where Terraform module sources are cached before running any Terraform command, helping you maintain a clean workspace and isolate module downloads per project or environment.

​
What Is download_dir?

  • Purpose: Defines the folder on your local file system where Terragrunt will store downloaded Terraform configurations and module dependencies.
  • Type: String (absolute or relative path).
  • Use Cases:
    • Organizing module downloads by project.
    • Separating cache directories for different environments or teams.
    • Keeping CI/CD pipelines’ caches isolated.
The download_dir path can be absolute or relative. If the directory doesn’t exist, Terragrunt will attempt to create it.

​
Key Benefits

BenefitDetails
CustomizationSelect any directory to store Terraform modules instead of the default cache.
OrganizationKeep downloaded modules apart from your working files and avoid clutter.
IsolationUse different download directories for separate pipelines, teams, or environments.

​
Considerations

  • Ensure the specified directory exists or is creatable by Terragrunt.
  • Verify file-system permissions to allow read/write operations.
  • Confirm sufficient disk space is available to store module downloads.
If download_dir lacks write permissions or runs out of space, Terragrunt may fail during init, interrupting your Terraform workflow.
The image is an infographic titled "Download dir" with icons and text indicating the need for necessary permissions and directory accessibility, labeled under "Consideration."

​
Demonstration

​
Default Behavior

With no download_dir set in your terragrunt.hcl, Terragrunt uses a hidden cache folder under your current working directory: 
~/workspace/vpc
$ terragrunt init
INFO[0000] Downloading Terraform configurations from tfr://terraform-aws-modules/vpc/aws?version=5.8.1 \
into /workspace/vpc/.terragrunt-cache/5eyWb_1sjaAZ9XRFnWys_PGxK0E/ThyVwttki6d6ASaD5OwoqIWA
...
Terraform has been successfully initialized!

​
Custom Download Directory

Add download_dir to your terragrunt.hcl at the root of your module: 
terraform {
  source = "tfr://terraform-aws-modules/vpc/aws//?version=5.8.1"
}

include "root" {
  path   = find_in_parent_folders()
  expose = true
}

download_dir = "../.terragrunt-kodekloud"

inputs = {
  name = "KodeKloud-VPC"
  cidr = "10.100.0.0/16"
}
Running initialization again stores the module cache in your custom directory: 
~/workspace/vpc
$ terragrunt init
INFO[0000] Downloading Terraform configurations from tfr://terraform-aws-modules/vpc/aws?version=5.8.1 \
into ../.terragrunt-kodekloud/5eyWb_lsjAZ9XrfnWJs_pGxNOE/ThyYwttki6d6ASaD5OwoqIAW
Initializing the backend...
Initializing provider plugins...
- Reusing previous versions of hashicorp/aws from the dependency lock file
- Installing hashicorp/aws v5.52.0...
Terraform has been successfully initialized!
Notice the cache now resides under ../.terragrunt-kodekloud instead of the default .terragrunt-cache.

Watch Video