Andrew Mercer
on this page

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:

  1. TFENV_TERRAFORM_VERSION / TENV_... environment variables
  2. .terraform-version in the current or a parent directory
  3. .tfswitchrc, .tool-versions
  4. required_version in the terraform block (tenv picks the newest installed or installable version that satisfies it)
  5. 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:

  1. Version file (.terraform-version / mise.toml) for humans.
  2. required_version in 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.

  1. 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.