Provider caching and mirrors in Terraform - Commands & Configuration

Introduction

Terraform uses providers to interact with cloud services. Sometimes downloading providers can be slow or unreliable. Provider caching and mirrors help speed up downloads and improve reliability by storing providers locally or using alternative sources.

When you want to speed up Terraform runs by avoiding repeated downloads of providers.

When your network has limited or unreliable internet access to the official Terraform provider registry.

When you want to use a private or internal mirror of providers for security or compliance reasons.

When working in a team and you want everyone to use the same provider versions from a shared cache.

When you want to reduce external dependencies in automated CI/CD pipelines.

Config File - terraform.rc

terraform.rc

provider_installation {
  filesystem_mirror {
    path    = "/usr/local/share/terraform/providers"
    include = ["registry.terraform.io/hashicorp/*"]
  }
  direct {
    exclude = ["registry.terraform.io/hashicorp/*"]
  }
}

This configuration file tells Terraform to look for providers first in a local folder /usr/local/share/terraform/providers for all HashiCorp providers. If not found there, it will try to download directly from the official registry.

provider_installation: Main block to configure provider sources.

filesystem_mirror: Defines a local folder mirror for providers matching the include pattern.

direct: Fallback to download providers directly from the registry if not found in the mirror.

Commands

Initializes Terraform, downloads providers using the caching and mirror settings from terraform.rc.

Terminal

terraform init

Expected Output

Initializing the backend...



Initializing provider plugins...

- Finding hashicorp/aws versions matching ">= 3.0.0"

- Installing hashicorp/aws v4.50.0...

- Installed hashicorp/aws v4.50.0 (signed by HashiCorp)



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.

Lists cached provider files in the local mirror directory to verify caching.

Terminal

ls /usr/local/share/terraform/providers

Expected Output

registry.terraform.io

Shows the providers Terraform is using for the current configuration and their sources.

Terminal

terraform providers

Expected Output

Providers required by configuration:

.

├── provider[registry.terraform.io/hashicorp/aws]



Provider source addresses:

- registry.terraform.io/hashicorp/aws

Key Concept

If you remember nothing else from this pattern, remember: configuring provider caching and mirrors lets Terraform reuse providers locally to save time and improve reliability.

Common Mistakes

Not creating or populating the local mirror directory with provider files.

Terraform will try to download providers directly if the mirror folder is empty, defeating the purpose of caching.

Download providers once with internet access, then copy them into the mirror folder for offline or faster reuse.

Misconfiguring the include or exclude patterns in terraform.rc.

Terraform may skip the mirror or try to download providers unnecessarily if patterns do not match provider addresses.

Use correct glob patterns matching the provider source addresses exactly, e.g., "registry.terraform.io/hashicorp/*".

Placing terraform.rc in the wrong location or with wrong filename.

Terraform will not read the configuration and caching will not work.

Place terraform.rc in the home directory or the directory where Terraform is run, with exact filename terraform.rc.

Summary

Create a terraform.rc file to configure provider caching and mirrors.

Use terraform init to initialize and download providers using the cache or mirror.

Verify cached providers exist in the local mirror directory.

Use terraform providers to check which providers are used and their sources.