Browse HashiCorp Certification Guides

Terraform Provider Requirements and Lock Files

April 13, 2026

How Terraform declares provider source addresses and version constraints, and records selected provider packages in its dependency lock file.

On this page

A Terraform provider is a plugin that implements Terraform’s interface to a remote system, such as AWS, GitHub, Kubernetes, or an internal API. A root module declares the providers it needs in required_providers; a provider configuration then supplies settings such as a region or endpoint. These are separate responsibilities. HashiCorp’s provider-requirements reference covers the declaration and selection rules.

Requirements, configuration, and the lock file

Item Purpose Usually lives in
Provider requirement Names a provider’s source address and acceptable versions. terraform { required_providers { ... } }
Provider configuration Supplies provider-specific settings, such as an AWS region. provider "aws" { ... }
Dependency lock file Records the selected provider packages and checksums. .terraform.lock.hcl
State Maps Terraform resource instances to remote objects. A local or remote state backend

For example, this configuration says that the local name aws refers to the hashicorp/aws provider and accepts versions in the 5.x line. The provider block selects a region for its default configuration.

 1terraform {
 2  required_providers {
 3    aws = {
 4      source  = "hashicorp/aws"
 5      version = "~> 5.0"
 6    }
 7  }
 8}
 9
10provider "aws" {
11  region = "ca-central-1"
12}

Run terraform init after adding or changing a requirement. Locally, it installs a version that satisfies the constraints and updates .terraform.lock.hcl with the selected package checksums. Commit the lock file alongside the configuration so compatible machines and remote runs can use the same provider selection. The lock file does not lock module versions and is not Terraform state.

Choosing version constraints

A version constraint expresses compatibility, not a promise that every future release is safe for an application. In reusable modules, HashiCorp recommends declaring the minimum provider version the module needs. A root module can apply a more restrictive upper bound when it needs to control upgrades across the whole deployment.

Before changing a constraint, read the provider’s release notes and run a plan in an appropriate environment. Updating a lock file with terraform init -upgrade can select newer allowed versions; review that resulting change as deliberately as any other dependency update.

Common mistakes

  • A provider is not a backend. Providers interact with remote APIs; a backend stores state and may provide locking.
  • A provider requirement is not provider configuration. A child module may declare what it requires without embedding credentials or a deployment-specific region.
  • Do not put long-lived credentials in configuration or the lock file. Use the provider’s supported authentication mechanisms and keep secrets out of source control.
  • Provider local names normally match the provider’s preferred type name. When two providers share a type name, choose distinct local names and specify the provider explicitly where Terraform cannot infer it.
Revised on Friday, September 11, 2026
Provider Aliases and State