tofuenv: Manage OpenTofu Versions in CI
tofuenv is the tfenv-style manager for OpenTofu: tofuenv install <version> and tofuenv use switch the tofu binary, reading .opentofu-version.
OpenTofu is the open-source fork of Terraform; tofuenv is the matching version manager, modeled on tfenv. Pipelines that moved off Terraform 1.6+ licensing use it to pin tofu.
What it does
tofuenv installs multiple OpenTofu (tofu) binaries and switches the active one via a shim, mirroring tfenv. The pin file is .opentofu-version (it also reads .terraform-version for compatibility), and it supports exact versions, latest, and latest:<regex>.
Common usage
tofuenv install 1.7.2
tofuenv use 1.7.2
echo "1.7.2" > .opentofu-version
tofuenv install # installs the pinned version
tofu versionOptions
| Command / value | What it does |
|---|---|
| tofuenv install <v> | Install a specific OpenTofu version |
| tofuenv install latest | Install the newest release |
| tofuenv use <v> | Switch the active version |
| tofuenv list-remote | List available versions |
| .opentofu-version | Pin file (also reads .terraform-version) |
| TOFUENV_ROOT | Override install directory |
In CI
Commit .opentofu-version and run tofuenv install. OpenTofu releases are GPG-signed; tofuenv can verify them, so the runner needs gpg and network access to GitHub releases. Cache $TOFUENV_ROOT/versions. The binary is tofu, not terraform, so update scripts accordingly.
Common errors in CI
"No installed versions of opentofu matched" means the pinned version was not installed; run tofuenv install. "gpg: Can't check signature" or a verification failure means gpg is missing or the key was not imported; install gnupg or set TOFUENV_SKIP_VERIFY only if you accept the risk. "tofuenv: tofu: command not found" means the bin dir is off PATH.