Skip to main content
In this guide, you’ll learn how to enforce Terraform and Terragrunt version constraints directly within your Terragrunt configuration. By pinning approved versions of the binaries, you’ll avoid unexpected upgrades and ensure consistency across your infrastructure deployments.
The image illustrates the benefits and considerations of using terraform_version_constraint and terragrunt_version_constraint attributes, highlighting version limitations and compatibility with setting constraints.

​
Why Version Constraints?

Use version constraints to:
  • Guarantee compatibility with existing state and modules
  • Prevent accidental upgrades during CI/CD runs
  • Enforce organizational compliance on approved tool versions
Always review your infrastructure modules and provider versions before updating constraints to avoid breaking changes.

​
Key Attributes

AttributePurposeExample
terraform_version_constraintLocks the Terraform binary to a specific semver range= 1.8.4
terragrunt_version_constraintRestricts the Terragrunt binary to a given range> 0.58.0, <= 0.58.11

​
Terraform Version Constraint Example

Below is a terragrunt.hcl snippet that requires Terraform 1.8.4: 
terraform {
  source = "tfr://terraform-aws-modules/vpc/aws//?version=5.8.1"
}

include "root" {
  path   = find_in_parent_folders()
  expose = true
}

inputs = {
  name = "KodeKloud-VPC"
  cidr = "10.100.0.0/16"
}

download_dir                 = "../.terragrunt-kodekloud"
prevent_destroy              = false
skip                         = false
iam_role                     = "arn:aws:iam::654654587009:role/terragrunt-role"
terraform_version_constraint = "= 1.8.4"
When a non-matching Terraform binary is detected, Terragrunt exits with an error: 
~/workspace/vpc > terragrunt plan
ERROR[0000] The currently installed version of Terraform (1.9.0) is not compatible with the version Terragrunt requires (= 1.8.4).
ERROR[0000] Unable to determine underlying exit code, so Terragrunt will exit with error code 1
To proceed, you can update or comment out the constraint to match your installed version: 
# terraform_version_constraint = "= 1.8.4"

~/workspace/vpc > terragrunt plan
aws_vpc.this[0]: Refreshing state... [id=vpc-0d98d39c5a645c65f]
aws_default_security_group.this[0]: Refreshing state... [id=sg-0617b0ec3422dbc5]
No changes. Your infrastructure matches the configuration.

​
Terragrunt Version Constraint Example

To restrict the Terragrunt binary, add terragrunt_version_constraint. The following example allows any version greater than 0.58.0 and up to 0.58.11: 
terraform {
  source = "tfr://terraform-aws-modules/vpc/aws//?version=5.8.1"
}

include "root" {
  path   = find_in_parent_folders()
  expose = true
}

inputs = {
  name = "KodeKloud-VPC"
  cidr = "10.100.0.0/16"
}

download_dir                  = "../.terragrunt-kodekloud"
prevent_destroy               = false
skip                          = false
iam_role                      = "arn:aws:iam::654645487009:role/terragrunt-role"
terraform_version_constraint  = "= 1.8.4"
terragrunt_version_constraint = "> 0.58.0, <= 0.58.11"
When your local Terragrunt is outside the specified range, all commands will fail: 
~/workspace/vpc > terragrunt -version
terragrunt version v0.58.12

~/workspace/vpc > terragrunt plan
ERROR[0000] The currently installed version of Terragrunt (0.58.12) is not compatible with the version Terragrunt requires (> 0.58.0, <= 0.58.11).
ERROR[0000] Unable to determine underlying exit code, so Terragrunt will exit with error code 1
Locking to very specific versions can block legitimate upgrades. Plan your version bumps carefully and test in a staging environment.

Watch Video