How do you run Terraform providers from a local or air-gapped mirror?

To run Terraform where the public registry is unreachable, copy the providers into a directory with terraform providers mirror, then configure a filesystem_mirror in the CLI configuration. Add official checksums to the lock file so the mirror is checked against the origin.

Step 1: build the mirror

On a machine with registry access:

terraform providers mirror -platform=linux_amd64 ./mirror

Terraform creates the directory structure it expects and fills it with the provider zip files. It also writes index files that can serve the network mirror protocol if you upload the folder to a static host. For a filesystem mirror, Terraform ignores those index files and treats the directory entries as authoritative.

By default the command uses the lock file versions if the directory was already initialized, and it builds for the platform where you run it unless you pass -platform.

Step 2: point Terraform at the mirror

In the CLI configuration file, a provider_installation block selects the method:

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

Each installation method accepts include and exclude patterns, and exclusions win if both match. A direct block fetches from the origin registry. A network_mirror block uses an HTTPS server.

Step 3: protect the mirror with checksums

A first install from a mirror cannot verify checksums for other platforms. HashiCorp suggests running terraform providers lock to pre-populate the official checksums, after which terraform init verifies that the packages in your mirror match the official ones. Without this step, a mirror is trusted simply because it is your mirror.

Choosing a method

Operational checks

• Restrict who can write to the mirror, since it becomes your provider source.
• Rebuild the mirror when provider versions change, and review the lock file diff in the same pull request.
• Keep the platform list in sync with the platforms that run Terraform.

Try it yourself

Click through it at your own pace, or open it full screen. Notice how a changed dependency gets flagged over time, the same habit you want for a provider mirror.

Quick check

Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.

Sources

• Terraform docs: terraform providers mirror
• Terraform docs: CLI configuration file
• Terraform docs: terraform providers lock

Last reviewed: 19 October 2026.