Different repos need different Terraform versions: the legacy stack on 1.9, new work on 1.16, an OpenTofu experiment on 1.12. A version manager installs several versions side by side and picks the right one per directory.
Which one¶
| Tool | Manages | Written in | Notes |
|---|---|---|---|
| tenv | Terraform, OpenTofu, Terragrunt, Terramate, Atmos | Go, single binary | Verifies signatures/checksums; reads required_version; the best fit for a Terraform + OpenTofu + Terragrunt toolchain |
| tfenv | Terraform only | Bash | The original; still works; no OpenTofu or Terragrunt |
| mise | Almost anything (Terraform, OpenTofu, Terragrunt, tflint, Rust, Node, Python…) | Rust | One tool for your whole dev environment; mise.toml per repo |
| asdf | Almost anything, via plugins | Bash (Go in newer versions) | mise is a faster, compatible successor |
Recommendation: tenv if you only want the IaC tools managed, mise if you'd like one file per repo that pins tflint, trivy and your Rust toolchain alongside Terraform.
tenv¶
# Fedora: grab the RPM from the GitHub releases page, or:
LATEST=$(curl -s https://api.github.com/repos/tofuutils/tenv/releases/latest | jq -r .tag_name)
curl -sLO "https://github.com/tofuutils/tenv/releases/download/${LATEST}/tenv_${LATEST}_amd64.rpm"
sudo dnf -y install "./tenv_${LATEST}_amd64.rpm"
# macOS
brew install tenv
tenv installs proxy binaries (terraform, tofu, terragrunt) that pick the version for the current directory.
tenv tf install 1.16.6
tenv tf install latest
tenv tf use 1.16.6 # writes the default version
tenv tf list
tenv tofu install 1.12.2
tenv tg install latest # Terragrunt
tenv tf detect # show which version this directory resolves to
How the version is chosen¶
For Terraform, roughly in order:
TFENV_TERRAFORM_VERSION/TENV_...environment variables.terraform-versionin the current or a parent directory.tfswitchrc,.tool-versionsrequired_versionin theterraformblock (tenv picks the newest installed or installable version that satisfies it)- The global default
OpenTofu uses .opentofu-version; Terragrunt .terragrunt-version. Set TENV_AUTO_INSTALL=true to download missing versions on first use.
echo "1.16.6" > .terraform-version # commit this
tfenv¶
git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc
tfenv install 1.16.6
tfenv use 1.16.6
tfenv install min-required # newest version satisfying required_version
Also reads .terraform-version. Fine if Terraform is all you need.
mise¶
curl https://mise.run | sh # read it first; or: sudo dnf install mise (Fedora COPR/packages)
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
# mise.toml (commit it)
[tools]
terraform = "1.16.6"
opentofu = "1.12.2"
terragrunt = "1.0.3"
tflint = "0.59.1"
trivy = "latest"
terraform-docs = "latest"
rust = "1.90"
[env]
TF_PLUGIN_CACHE_DIR = "{{env.HOME}}/.terraform.d/plugin-cache"
mise install # install everything the repo pins
mise ls
The version numbers above are illustrative. Pin what you actually run. mise also reads .terraform-version and .tool-versions.
Pin in three places¶
Keep these consistent:
- Version file (
.terraform-version/mise.toml) for humans. required_versionin the root module, which enforces it:
hcl
terraform {
required_version = "~> 1.16.0" # root modules: tight
}
Modules should use a lower bound for features they need (>= 1.9), not an upper pin.
- CI image tag (
hashicorp/terraform:1.16.6, or your own toolchain image).
Renovate can bump all three together (required_version, .terraform-version via its regex or asdf/mise managers, and Docker image tags), so upgrades arrive as one MR per release.