Yes, if you keep the dependency lock file committed and leave the may-break option at its default. Terraform's plugin cache reuses downloaded providers across workspaces. HashiCorp recommends that most users leave plugin_cache_may_break_dependency_lock_file unset, so Terraform installs a provider from upstream the first time, and then reuses the cache.
What the cache does
The plugin_cache_dir setting in the CLI configuration enables plugin caching and gives the directory. Without it, every working directory downloads its own copy of each provider. With it, repeated inits on the same machine reuse files, which saves time and bandwidth, and reduces load on the registry.
In CI, that is attractive, because pipelines often run init in a fresh checkout many times a day.
How it meets the lock file
The lock file records which provider versions and checksums your configuration expects. The Terraform documentation explains the default behavior: Terraform installs a provider from upstream the first time you use it with a particular configuration, records valid checksums, and from then on can reuse the cache entry.
There is an opt in setting, plugin_cache_may_break_dependency_lock_file, also available as an environment variable. When on, it lets Terraform create an incomplete lock file entry if that lets it use the cache. The entry can contain only a checksum of the package in the global cache. The result is valid on that machine but may not be valid on another machine with a different operating system or CPU architecture, because it would not include the other platforms' checksums.
HashiCorp recommends most users leave it unset, and says it intends to improve the mechanism so the option will later be silently ignored.
Risks to manage
| Risk | Why it happens | Mitigation |
|---|---|---|
| Incomplete lock entries | The may-break option is on | Leave it off in shared pipelines |
| Poisoned cache | A shared cache directory is writable by other jobs | Use a per job or per branch cache with restricted access |
| Stale providers | Cache keyed on nothing | Key the cache on the lock file hash |
| Mixed platforms | Lock file made on one platform only | Generate checksums for every platform you run |
The cache is only as trustworthy as who can write to it. If a pull request from a fork can populate a cache that a later privileged job restores, a hostile provider could persist into a trusted run. Keep untrusted jobs and trusted jobs on separate cache keys, and do not restore caches written by untrusted workflows.
A safe CI recipe
- Commit the lock file and review changes to it like code.
- Generate checksums for each platform your runners and developers use. See Terraform providers lock: what it does and when to run it.
- Set the cache directory to a path inside the job workspace.
- Key the CI cache on a hash of the lock file.
- Do not set the may-break option.
- Run init in read only lock mode so a drifting lock file fails the build. See terraform init lockfile readonly in CI.
What to watch for
If init suddenly downloads from the internet on every run, your cache key is wrong. If it never downloads, check that the cache is not being restored from an unreviewed source. Log the provider versions and checksums used, and keep them with the plan output.
Where a scanner fits
Providers are code you execute with cloud credentials, so inventory them. Safeguard's SBOM generation and dependency scanning, plus policy gates on pull requests, can help you notice changes to lock files and review them. Confirm how your scanner treats lock files in Terraform repositories. Free scan: gold.safeguard.sh/scan.
Quick check
Should I enable plugin_cache_may_break_dependency_lock_file?
HashiCorp recommends most users leave it unset. Enabling it can produce lock entries that only include the cached package's checksum, which may fail on other platforms.
Does the cache replace the lock file?
No. The cache saves downloads. The lock file records the versions and checksums you expect. Use both.
Sources
Last reviewed: 19 October 2026.
