Must have Terraform Configurations

If you've ever watched terraform init download hundreds of megabytes of provider plugins for the dozenth time, you know the pain. While Terraform's automatic dependency management is convenient, repeatedly downloading the same provider binaries can slow down your workflow and rack up unnecessary network costs—especially in CI/CD pipelines.

The solution? Configure Terraform to cache provider plugins locally.

The Problem with Default Behavior

By default, Terraform queries the Terraform Registry and downloads required providers every time you run terraform init. For a fresh project or when updating versions, this makes sense. But when you're running the same initialization repeatedly—whether locally during development or in automated pipelines—you're downloading the same files over and over.

Consider this: the AWS provider version 6.23 weighs in at 762MB (163.7MB zipped). In a CI/CD environment executing dozens or hundreds of builds per day, that bandwidth adds up quickly.

The Solution: Plugin Cache Directory

Terraform supports a plugin cache through the .terraformrc configuration file. By adding a single line, you can dramatically improve initialization speed:

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

With this setting, Terraform checks the cache directory first before reaching out to the registry. If the required provider and version already exist locally, Terraform uses the cached copy instead of downloading it again.

Download without Cache

We can see the difference in action. First, without the cache configured: Total 19.703 seconds

➜  local-test time terraform init
Initializing the backend...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Installing hashicorp/aws v6.23.0...
- Installed hashicorp/aws v6.23.0 (signed by HashiCorp)

Terraform has been successfully initialized!

terraform init  5.22s user 1.66s system 34% cpu 19.703 total

Download with Cache

Now, with the plugin cache enabled: Total 1.384 seconds

Initializing the backend...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Using hashicorp/aws v6.23.0 from the shared cache directory

Terraform has been successfully initialized!

terraform init  0.94s user 0.26s system 86% cpu 1.384 total

One thing to note is that the .terraform.lock.hcl file must be present for the cache to be effective, as it specifies the checksums for each provider version.

Set plugin_cache_may_break_dependency_lock_file = true in your .terraformrc to utilize the cache without a lock file.

➜  local-test time terraform init
Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 6.0"...
- Using hashicorp/aws v6.23.0 from the shared cache directory
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

╷
│ Warning: Incomplete lock file information for providers
│
│ Due to your customized provider installation methods, Terraform was forced to calculate lock file checksums locally for the following providers:
│   - hashicorp/aws
│
│ The current .terraform.lock.hcl file only includes checksums for darwin_arm64, so Terraform running on another platform will fail to install these providers.
│
│ To calculate additional checksums for another platform, run:
│   terraform providers lock -platform=linux_amd64
│ (where linux_amd64 is the platform to generate)
╵
Terraform has been successfully initialized!

terraform init  0.36s user 0.19s system 56% cpu 0.969 total

Benefits

• Faster initialization: Skip network requests and downloads entirely for cached providers
• Reduced CI/CD time: Your pipelines spend less time waiting for dependencies
• Lower network costs: Particularly valuable in metered or bandwidth-constrained environments
• Offline capability: Work with cached providers even without internet connectivity

Recommended Configuration

Here's a proven configuration that includes both plugin caching and credential management for private registries:

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

credentials "gitlab.com" {
  token = "my-token"
}

credentials "app.terraform.io" {
  token = "my-hcp-token"
}

Important Maintenance Note

Terraform doesn't automatically clean up the plugin cache. Over time, as you update provider versions, old binaries accumulate in the cache directory. Make it a habit to periodically prune older versions or clear the cache entirely to reclaim disk space.

Additional Options

The .terraformrc file supports numerous other configuration options beyond plugin caching, including development provider overrides and credential helpers for various registry types. You can also use the TF_CLI_CONFIG_FILE environment variable to point to an alternate configuration file location—useful for managing different configurations across projects or environments.

For the complete list of CLI configuration options, refer to the official Terraform CLI configuration documentation.

Simple optimizations like plugin caching can have outsized impacts on developer productivity and infrastructure costs. If you're not already using a .terraformrc file, now's the time to start.