Category: tfenv

How to manage multiple terraform versions with tfenv

You can use tfenv use to quickly switch between the different terraform versions you have installed on your system:

> tfenv use 1.1.8
> terraform --version
Terraform v1.1.8

> tfenv use 0.13.5
> terraform --version
Terraform v0.13.5

If the version is not installed already, you can use tfenv install to install it e.g. to install terraform v1.1.8:

tfenv install 1.1.8

Finally, you can check all the existing versions you have installed via tfenv list, e.g. in my case:

>  tfenv list
* 1.1.8
0.13.5

Note: the wildcard character is preffixing the version currently used by default.

tfenv commands

The most used and useful commands are:

  • tfenv list
  • tfenv use <version>
  • tfenv install <version>

More can be displayed on the manual:

> tfenv
tfenv 3.0.0
Usage: tfenv <command> [<options>]

Commands:
   install       Install a specific version of Terraform
   use           Switch a version to use
   uninstall     Uninstall a specific version of Terraform
   list          List all installed versions
   list-remote   List all installable versions
   version-name  Print current version
   init          Update environment to use tfenv correctly.
   pin           Write the current active version to ./.terraform-version

How to install tfenv

Using brew (MacOS)

brew install tfenv

Via the Github repository

  1. Git clone the tfenv repository under a new tfenv folder:

    git clone https://github.com/tfutils/tfenv.git ~/.tfenv

  2. Export the path to your profile:

    For bash users:

    echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bash_profile

    For MacOS:

    echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.zshrc

  3. Turn tfenv/ into an executable binary. Thus, you can symlink it to your local bin directory:

    ln -s ~/.tfenv/bin/* /usr/local/bin

  4. Check that the tfenv/ binary folder is indeed synchronized with the local/bin directory:

    > which tfenv
/usr/local/bin/tfenv

  5. Check the installation:

    > tfenv --version
tfenv 3.0.0

Which terraform versions are available

You can check the exisitng available terraform versions on the official hashicorp releases page: releases.hashicorp.com/terraform.

Note: similarly you can use the command line interface:

> tfenv list-remote
1.3.4
1.3.3
1.3.2
1.3.1
1.3.0
1.3.0-rc1
1.3.0-beta1
1.3.0-alpha20220817

When to use tfenv and why it is useful

tfenv allows you to quickly change the version of terraform running by default on your system.

This is handy when you have multiple terraform repositories across your organization and each one of them uses a different terraform version.

To be more specific, each terraform repository requires you to set the terraform version explicitely, as you can see line 2 of the following example:

terraform {
    required_version = "1.2.2"
    required_providers {
        local = {
            source = "hashicorp/local"
            version = "~> 2.0"
        }
    }
}

When using the usual methods:

  • terraform init
  • terraform plan
  • teraform apply

it will require you to have a local terraform version matching the one specified in the terraform configuration file.

Therefore, the 1:1 mapping between your locally installed versions and the versions specified in your configuration files is required.

Warning: running one of those methods with a higher local terraform version will introduces changes on your repository that cannot be reversed. This will not only forces you to migrate the configuration files so they fit the syntax of the new terraform version, but all developers will have to install the new terraform version on their local environment too.

Swapping has never been easier! 🔥