How to Manage Multiple OpenTofu Versions With Tofuenv
Tags: terraform, opentofu, tofuenv, devops
Published: 2024-01-09 21:14:41

When we work with only one [OpenTofu](https://github.com/opentofu/opentofu) project, we install needed version and don’t have any issues. But when we start to work with multiple projects with different versions of  OpenTofu - we are in trouble.

How could this problem be solved earlier? We downloaded the required version of OpenTofu and placed it somewhere in `$PATH`. After that we renamed the downloaded file and used it something like this:

```
$ tofu-1.6.0-rc1 -version
OpenTofu v1.6.0-rc1
on darwin_amd64
```

But this is hard and inconvenient to switch between versions, and we need to remember, which version of OpenTofu has to be used every time.

Here [tofuenv](https://github.com/tofuutils/tofuenv) is going to help us. tofuenv is an OpenTofu version manager. It allows us to easily install a version, switch between them, and set specific version for specific repository.

## Installing tofuenv

tofuenv can be installed to all major operating systems, such as MacOS, Linux and Windows.

We can use brew to install tofuenv to the macos:
```
$ brew tap tofuutils/tap
$ brew install tofuenv
```
For linux, we can manually install tofuenv.

Check out tofuenv into any path (here is `${HOME}/.tofuenv`)
```
$ git clone --depth=1 https://github.com/tofuutils/tofuenv.git ~/.tofuenv
```
Add `~/.tofuenv/bin` to your `$PATH` any way you like:

bash:
```
$ echo 'export PATH="$HOME/.tofuenv/bin:$PATH"' >> ~/.bash_profile
```
zsh:
```
$ echo 'export PATH="$HOME/.tofuenv/bin:$PATH"' >> ~/.zprofile 
```
OR you can make symlinks for `tofuenv/bin/*` scripts into a path that is already added to your `$PATH` (e.g. `/usr/local/bin`) OSX/Linux Only!
```
$ ln -s ~/.tofuenv/bin/* /usr/local/bin
```
On Ubuntu/Debian touching `/usr/local/bin` might require sudo access, but you can create `${HOME}/bin` or `${HOME}/.local/bin` and on next login it will get added to the session `$PATH` or by running . `${HOME}/.profile` it will get added to the current shell session's `$PATH`.
```
$ mkdir -p ~/.local/bin/ 
$ . ~/.profile
$ ln -s ~/.tofuenv/bin/* ~/.local/bin 
$ which tofuenv
```
Run tofuenv to verify installation and check available options:
```
$ tofuenv
tofuenv 1.0.3
Usage: tofuenv <command> [<options>]

Commands:
   install       Install a specific version of OpenTofu
   use           Switch a version to use
   uninstall     Uninstall a specific version of OpenTofu
   list          List all installed versions
   list-remote   List all installable versions
   version-name  Print current version of OpenTofu
   init          Update environment to use tofuenv correctly.
   pin           Write the current active version to ./.opentofu-version
```
In case of any problems, you may refer to official documentation at [tofuenv github repository](https://github.com/tofuutils/tofuenv).

## Installing OpenTofu with tofuenv

After we have tofuenv installed, we can install opentofu in the following way.

To install specific version of opentofu use the following command:
```
$ tofuenv install 1.6.0-rc1
```
To install latest stable version we can use specific word latest:
```
$ tofuenv install latest
```
But due to the fact that at the time of writing this article OpenTofu doesn’t have a stable version, installation via `latest` word doesn't work.

Anyway, we can install  the latest available version of OpenTofu 1.6:
```
$ tofuenv install latest:1.6
tofuenv install latest:1.6
Installing OpenTofu v1.6.0-rc1
Downloading release tarball from https://github.com/opentofu/opentofu/releases/download/v1.6.0-rc1/tofu_1.6.0-rc1_darwin_amd64.zip
########################################################################################################################################################### 100.0%
Downloading SHA hash file from https://github.com/opentofu/opentofu/releases/download/v1.6.0-rc1/tofu_1.6.0-rc1_SHA256SUMS
Archive:  /var/folders/nb/k6bv49gd4pd9kyvwwn519_2m0000gn/T/tofuenv_download.XXXXXX.fqdxfWoz/tofu_1.6.0-rc1_darwin_amd64.zip
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/CHANGELOG.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/LICENSE  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/README.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-rc1/tofu  
Installation of tofu v1.6.0-rc1 successful. To make this your default version, run 'tofuenv use 1.6.0-rc1'
```
For now the latest available version of OpenTofu 1.6 is 1.6.0-rc1 and for that reason, it was installed by tofuenv.

**Note:** If shasum is present in the path, tofuenv will verify the download against OpenTofu published sha256 hash. Also GPG signature will be added for verification as soon as OpenTofu will support it.

## List OpenTofu versions

With tofuenv we can list locally installed versions and remote versions, which are available for installation.

To list locally installed versions, run the following command:
```
$ tofuenv list
  1.6.0-alpha1
* 1.6.0-rc1 (set by /usr/local/Cellar/tofuenv/1.0.3/version)
```
Asterisk marks the version currently used.

To list remote versions, run the following command:
```
$ tofuenv list-remote
1.6.0-rc1
1.6.0-beta5
1.6.0-beta4
1.6.0-beta3
1.6.0-beta2
1.6.0-beta1
1.6.0-alpha5
1.6.0-alpha4
1.6.0-alpha3
1.6.0-alpha2
1.6.0-alpha1
```
OpenTofu placed binary in GitHub, and GitHub has a strict rate limiting rule for non-authorised users. Because of this, you can catch the 403 error or "GitHub Rate limits exceeded" error. You can set environment variable `TOFUENV_GITHUB_TOKEN` with your own GitHub token for authentication against GitHub api and drastically increase the rate limits.

## Switch a version to use

To switch between versions, we can use couple of techniques.

First of all, with use `use` parameter:
```
$ tofuenv use 1.6.0-alpha1
Switching default version to v1.6.0-alpha1
Default version (when not overridden by .opentofu-version or TOFUENV_TOFU_VERSION) is now: 1.6.0-alpha1
```
By default, environment variable `TOFUENV_AUTO_INSTALL` is set to `true`, and if version 1.6.0-alpha2 of OpenTofu isn’t available locally, it will be downloaded and used automatically:
```
$ tofuenv use 1.6.0-alpha2
No installed versions of opentofu matched '^1.6.0-alpha2$'. Trying to install a matching version since TOFUENV_AUTO_INSTALL=true
Installing OpenTofu v1.6.0-alpha2
Downloading release tarball from https://github.com/opentofu/opentofu/releases/download/v1.6.0-alpha2/tofu_1.6.0-alpha2_darwin_amd64.zip
########################################################################################################################################################### 100.0%
Downloading SHA hash file from https://github.com/opentofu/opentofu/releases/download/v1.6.0-alpha2/tofu_1.6.0-alpha2_SHA256SUMS
Archive:  /var/folders/nb/k6bv49gd4pd9kyvwwn519_2m0000gn/T/tofuenv_download.XXXXXX.3DyehSoJ/tofu_1.6.0-alpha2_darwin_amd64.zip
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/CHANGELOG.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/LICENSE  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/README.md  
  inflating: /usr/local/Cellar/tofuenv/1.0.3/versions/1.6.0-alpha2/tofu  
Installation of tofu v1.6.0-alpha2 successful. To make this your default version, run 'tofuenv use 1.6.0-alpha2'
Switching default version to v1.6.0-alpha2
Default version (when not overridden by .opentofu-version or TOFUENV_TOFU_VERSION) is now: 1.6.0-alpha2
```
Second option is to use `.opentofu-version` file. If that file is present in the directory and contains needed version, it will be used automatically:
```
project1$ tofu -version
OpenTofu v1.6.0-rc1
on darwin_amd64
project1$ cat .opentofu-version 
1.6.0-rc1

project1$ cd ../project2
project2$ tofu -version
OpenTofu v1.6.0-alpha1
on darwin_amd64
project2$ cat .opentofu-version 
1.6.0-alpha1
```
That file can be created manually, for example:
```
$ echo 1.6.0-alpha1 > .opentofu-version
```
Or with using special command `pin` from tofuenv. That command will save currently used version of opentofu to the file in current directory:
```
$ tofu -version
OpenTofu v1.6.0-rc1
on darwin_amd64

$ tofuenv pin
Pinned version by writing "1.6.0-rc1" to ./.opentofu-version
```

## Uninstall unneeded versions

For the cleanup of unneeded installed version we can use `uninstall` command:
```
$ tofuenv uninstall 1.6.0-rc1
Uninstall OpenTofu v1.6.0-rc1
OpenTofu v1.6.0-rc1 is successfully uninstalled
```

## In conclusion

[OpenTofu](https://github.com/opentofu/opentofu) is a great open-source alternative to Terraform. Our team of tofuenv creators (me, [Alexander Sharov](https://dev.to/kvendingoldo) and [Anastasiia Kozlova](https://dev.to/anastasiiakozlova245)) believes that OpenTofu will take decisive place in the market, and tofuenv will help everyone to use it successfully.