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
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 as2.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
- OpenTofu installed: How to Install OpenTofu on macOS.
- A terminal and an empty folder, such as
version-constraints.
Step 1: Write a Constraint
Create main.tf in the folder with this block:
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
tofu init
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!

OpenTofu installed 2.8.0, the newest version that matches, even though 2.9.1 exists.
What Each Constraint Allows
| Constraint | Versions of hashicorp/local it allows |
|---|---|
2.8.0 or = 2.8.0 | Only 2.8.0 |
~> 2.8.0 | 2.8.0 and later 2.8.x releases |
~> 2.8 | 2.8 and later 2.x releases, such as 2.9.1, but not 3.0 |
>= 2.8.0, < 3.0.0 | The same range as ~> 2.8 |
>= 2.8.0 | 2.8.0 and every later version, including future major releases |
!= 2.9.0 | Every 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.
Related
- OpenTofu Tutorial — Part 3: Providers: Run the Website in Docker
- What Does tofu init Do in OpenTofu?
Additional Resources
- Version Constraints (opens in a new tab)
- Provider Requirements (opens in a new tab)
- Dependency Lock File (opens in a new tab)
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