Skip to main content
0 reactions

OpenTofu Version Constraints Explained: ~>, >= and =

A Terminal window running tofu init: OpenTofu finds hashicorp/local versions matching the constraint ~> 2.8.0, installs hashicorp/local v2.8.0 and says it is signed.
With ~> 2.8.0, tofu init installs 2.8.0, the newest 2.8 release.

Every provider in an OpenTofu® project carries a version constraint, such as "~> 4.7". It tells tofu init which versions it may install. This guide explains the syntax and the operators, then shows one constraint at work.

Syntax

SyntaxHCL
version = "<operator> <version>, <operator> <version>, ..."
  • <operator>: how the version is compared. = (or none) allows one exact version; != excludes one; >, >=, < and <= compare; ~> lets only the rightmost number of the version go up.
  • <version>: a version number such as 2.8.0 (major.minor.patch).
  • Several conditions are separated by commas, and a version must meet all of them.

Every operator is described in Version Constraints (opens in a new tab) in the OpenTofu docs.

In this guide, the constraint "~> 2.8.0" picks a version of the hashicorp/local provider, whose newest release is 2.9.1.

Prerequisites

Step 1: Write a Constraint

Create main.tf in the folder with this block:

main.tfHCL
terraform {
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.8.0"
    }
  }
}

~> 2.8.0 ends in the patch number, so only the patch may go up: 2.8.0, 2.8.1 and so on, but not 2.9.

Step 2: Run tofu init

TerminalBash
tofu init
Output (the lines that matter)Plain text
Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/local versions matching "~> 2.8.0"...
- Installing hashicorp/local v2.8.0...
- Installed hashicorp/local v2.8.0 (signed, key ID 0C0AF313E5FD9F80)

Providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://opentofu.org/docs/cli/plugins/signing/

OpenTofu has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that OpenTofu can guarantee to make the same selections by default when
you run "tofu init" in the future.

OpenTofu has been successfully initialized!
A Terminal window running tofu init: OpenTofu finds hashicorp/local versions matching the constraint ~> 2.8.0, installs hashicorp/local v2.8.0 and says it is signed.
With ~> 2.8.0, tofu init installs 2.8.0, the newest 2.8 release.

OpenTofu installed 2.8.0, the newest version that matches, even though 2.9.1 exists.

What Each Constraint Allows

ConstraintVersions of hashicorp/local it allows
2.8.0 or = 2.8.0Only 2.8.0
~> 2.8.02.8.0 and later 2.8.x releases
~> 2.82.8 and later 2.x releases, such as 2.9.1, but not 3.0
>= 2.8.0, < 3.0.0The same range as ~> 2.8
>= 2.8.02.8.0 and every later version, including future major releases
!= 2.9.0Every version except 2.9.0

The OpenTofu docs recommend ~> in a project you run, so you get fixes and new features but never a new major version by surprise. A reusable module should set only a minimum, such as >= 2.8, so the projects that use it can choose newer versions.

Note: A constraint only limits the choice. Once tofu init has picked a version, the dependency lock file keeps it until you upgrade the provider.

Clean Up

Delete the version-constraints folder. Nothing outside it was created.

FAQ

What happens if no version matches?

OpenTofu can’t get an acceptable version, so it stops: it won’t plan or apply anything until the constraint or the available versions change.

Can a constraint select a preview release?

Only an exact constraint can. A prerelease such as 1.2.0-beta never matches >=, ~> or the other range operators.

Conclusion

A version constraint is a short rule in required_providers. ~> with two numbers, such as ~> 2.8, is the usual choice for a project: newer minor releases are allowed, a new major release isn’t.

Additional Resources

OpenTofu® is a registered trademark of LF Projects, LLC. Other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the OpenTofu project.

0 comments