• Developer
  • Infrastructure

Terraform downloads a copy of every provider into every project

Provider binaries are hundreds of megabytes and each project gets its own. The plugin cache setting that stops it, and how to clean up after the fact.

5 min read

Running terraform init downloads the providers a configuration needs into a .terraform folder inside that project. Do that in ten repositories and you have ten copies of the same provider binaries, each of which can be several hundred megabytes.

Find every copy

find ~ -type d -name .terraform -maxdepth 6 2>/dev/null \
  -exec du -sh {} + | sort -h | tail -20

Read that list for repetition rather than for size. The same provider version appearing in eight projects is the problem, and it has a one line fix that applies from then on.

The plugin cache, which everyone should set

mkdir -p ~/.terraform.d/plugin-cache
echo 'plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"' >> ~/.terraformrc

With that set, terraform init puts providers in one shared location and links to them from each project instead of downloading again. New projects stop paying the cost, and the shared cache is a single folder you can measure and prune.

Cleaning up what already exists

  1. Set the plugin cache first, or you will do this again next month.
  2. Delete .terraform folders in projects you are not actively applying.
  3. Run terraform init again when you return to one; it is a download, not a rebuild of state.
  4. Leave terraform.tfstate alone entirely.
find ~ -type d -name .terraform -maxdepth 6 2>/dev/null -print0 \
  | xargs -0 rm -rf   # after reading the list above

The one thing not to delete

State files. terraform.tfstate and its backups describe what actually exists in your infrastructure, and for a project using local state they are not recoverable from anything on your Mac. The .terraform folder is downloads; the state file is a record.

This is the same shape as every other dependency folder on a developer machine, and the general command for finding them across projects is in node_modules across every project.

Common questions

Why does every Terraform project download its own providers?

Because terraform init installs them into a .terraform folder inside the project by default. Without a shared plugin cache configured, each project keeps its own copy of the same binaries.

How do I set up a Terraform plugin cache?

Create a directory such as ~/.terraform.d/plugin-cache and add plugin_cache_dir pointing at it in ~/.terraformrc. Subsequent inits link to the shared copy instead of downloading again.

Is it safe to delete .terraform folders?

Yes. They hold downloaded providers and modules, restored by running terraform init. Do not delete terraform.tfstate files, which record the real state of your infrastructure.

How much space do Terraform providers use?

Hundreds of megabytes per provider version, and a project using several providers can exceed a gigabyte. Multiplied across projects without a shared cache, it is one of the larger hidden folders on an infrastructure machine.

Read next