The required_version setting specifies which Terraform CLI versions are allowed to run a configuration. If the CLI does not meet the constraint, Terraform prints an error and exits. It applies to the CLI only; provider plugin versions are set separately in required_providers. Use both so teammates and CI run the same tooling.
What the documentation says
HashiCorp's terraform block documentation states that required_version specifies which version of the Terraform CLI is allowed to run the configuration, and that a non-matching CLI causes an error and exit. It applies to the CLI, not provider plugins.
The required_providers block specifies all provider plugins required to create and manage the resources in the configuration. Each provider takes a version, the version the configuration must use, and a source, the global source address. If you omit the version, the page says Terraform installs the newest version by default.
terraform {
required_version = ">= 1.9.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = ">= 5.0"
}
}
}
The constraint values above are examples, not recommendations. The terraform block page links to a separate version constraints page for operator syntax, so read that before writing your own.
Why this is a patching control
Infrastructure code runs with strong credentials. An old CLI can lack fixes, and mixed CLI versions across a team cause confusing plan differences. A floor in required_version turns "please upgrade" into a failure message nobody can ignore.
Omitting a provider version has the opposite problem. Because Terraform installs the newest version by default, two runs on different days can differ. That is convenient for fixes and unpleasant for reproducibility.
Floors, ceilings and ranges
| Constraint style | Effect | Risk |
|---|---|---|
| Floor only | Blocks too-old versions | New major versions may behave differently |
| Floor and ceiling | Keeps the team in one range | Needs a scheduled bump |
| No constraint | Anything runs | Silent drift |
For most teams a floor plus a planned review works. Add a ceiling when a major release is known to need migration work.
A routine
- Add required_version to every root configuration.
- List providers in required_providers with source and version.
- Run a scheduled job that tries the newest CLI against a plan and reports failures.
- Bump the floor when you have tested it, and record why.
- Keep CI images and laptops on versions the constraint allows.
The Dependabot ecosystem list includes opentofu for version updates; see which dev tooling Dependabot can update. The page we reviewed did not clearly confirm Terraform itself in that list, so check it for your tool.
Safeguard scans infrastructure and dependency code in your repositories before merge. A free scan is at gold.safeguard.sh/scan.
Common mistakes
The typical slips are adding required_version to only some root modules, leaving provider versions unset so runs differ between days, and setting a ceiling and forgetting it exists until a new feature needs the newer release. Another is assuming the CLI constraint also covers providers, which the documentation says it does not.
Test a newer CLI in a separate branch on a schedule so the bump is routine, not an emergency.
Quick check
Does required_version control provider versions?
No. It applies to the Terraform CLI only. Provider versions are set in required_providers.
What happens if I omit a provider version?
Per the documentation, Terraform installs the newest version by default, so results can change between runs.
Sources
Last reviewed: 19 October 2026.
