A dependency version requirement controls which releases a project may use. In Terraform, a registry module’s `version` field gives an allowed range; its required `source` field identifies where the module comes from. Choosing a range lets a project accept suitable updates while avoiding releases outside its expectations. section 2.8 section 3.1.1
Select a registry module
`module "vpn" { source = "tedivm/cloudinit/general"; version = "~> 1.0"; services = ["consul", "nomad"] }` uses a registry source and a version requirement rather than selecting a single release. section 3.1.1
Version ranges work alongside semantic versioning: patch releases represent fixes, minor releases add features, and major releases signal backward-incompatible changes. For reusable modules, a practical starting point is the lowest version known to work while excluding the next major version. Wider supported ranges also reduce conflicts when a project uses several modules; they still need testing and responsible release versioning. section 8.1.1
Table 8.2 Example constraints with their allowed versions (view table figure)
| Constraint |
Allowed versions |
|---|---|
| = 1.1.1 |
Only v1.1.1 is allowed. |
| >= 1.1.0, < 2.0.0 |
The minimum version is v1.1.0, and any Minor or Patch versions are allowed. Upgrading the Major version is not allowed. |
| >= 1.1.0, < 2.0.0, != 1.3.2 |
The same as above, except we’re also forbidding version v1.3.2 from being used. Excluding specific versions is useful when bugs are introduced to a specific version and then fixed. |
| ~> 1.1.0 |
The pessimistic constraint operator allows only the rightmost field to be upgraded. In this case, that means v1.1 and any bug fixes are allowed, but Minor and Major upgrades are excluded. |
| ~> 1.1 |
This sets the floor at v1.1, but since the rightmost value is the Minor field it allows Minor and Patch upgrades. It is the exact same as >= 1.1.0, <2.0.0 but is more concise. |
Compare an exact pin with explicit bounds, an excluded buggy release, and two pessimistic constraints. `~> 1.1.0` permits patch updates within 1.1; `~> 1.1` also permits later minor releases below 2.0. section 8.1.1
The module `version` field applies to registry sources, not Git sources. A Git source can use `?ref=` to select a tag or commit, but that pins one reference instead of expressing an allowed range. Following a default branch avoids manual pins but can expose users to incompatible changes; a registry is preferable when teams need scalable, range-based module delivery. section 8.1.2
Engine versions are a related requirement. `tenv` reads `.terraform-version` or `.opentofu-version` to choose a project’s Terraform or OpenTofu binary; a file can specify an exact version such as `1.5.7` or a constraint such as `~>1.5`. Use `tenv tf use VERSION` or `tenv tofu use VERSION` to override that selection. The `min-required` and `latest-allowed` selections help test whether a claimed supported range works at its edges. section 7.2.5
