How to manage different terraform versions for each project

Warren Veerasingam
5 min readOct 24, 2018


A command-line tool to switch between different versions of terraform.

“We are trapped in a savage parallel universe from which we must escape within four hours, or I will face a death sentence at Mr. Spock’s hands”— Captain’s log, stardate unknown.
Unlike Star Trek, we don’t need to jump between different parallel universes to escape death.However, when building a complex infrastructure for multiple projects, we may have to jump between different versions of development tools.

Enter Terraform

Terraform lets you safely and predictably create, change, and improve infrastructure. It is an open source tool that codifies APIs into declarative configuration files that can be shared amongst team members, treated as code, edited, reviewed, and versioned.

As infrastructure providers like AWS, Azure, or Google Cloud Compute evolve and add new features, Hashicorp releases incremental versions of terraform to support these features. So, older projects may be on an older version while newer projects might require a newer version of terraform.

So, how do we switch between different versions of terraform?

Brew tap install terraform — tfswitch

The tfswitch command line tool lets you switch between different versions of terraform. If you do not have a particular version of terraform installed, tfswitch will download the version you desire. The installation is minimal and easy. Once installed, simply select the version you require from the dropdown and start using terraform.

tfswitch is available for MacOS and Linux based operating systems. To use brew, you need homebrew installed. Homebrew simplifies the install process and makes updating easy. To install brew :

MacOS with brew

brew install warrensbox/tap/tfswitch


Installation for Linux operation systems.

curl -L | bash

Install from source

Alternatively, you can install the tfswitch binary from the source here

How to use:

Use the dropdown menu to select a version

  1. You can switch between different versions of terraform by typing the command tfswitch on your terminal.
  2. Select the version of terraform you require by using the up and down arrow.
  3. Hit Enter to select the desired version.

The most recently selected versions are presented at the top of the dropdown.

Supply version on command line

  1. You can also supply the desired version as an argument on the command line.
  2. For example, tfswitch 0.10.5 for version 0.10.5 of terraform.
  3. Hit Enter to switch.

See all versions including beta, alpha and release candidates(RC)

  1. Display all versions including beta, alpha and release candidates(RC).
  2. For example, tfswitch -l or tfswitch --list-all to see all versions.
  3. Hit Enter to select the desired version.

Use file

If a .tf file with the terraform constrain is present in the current directory, it should automatically download or switch to that terraform version. For example, the following should automatically switch terraform to version 0.12.24:

terraform {
required_version = ">= 0.12.9"

required_providers {
aws = ">= 2.52.0"
kubernetes = ">= 1.11.1"

Use .tfswitch.toml file (For non-admin — users with limited privilege on their computers)

This is similar to using a .tfswitchrc file, but you can specify a custom binary path for your terraform installation

  1. Create a custom binary path. Ex: mkdir /Users/warrenveerasingam/bin (replace warrenveerasingam with your username)
  2. Add the path to your PATH. Ex: export PATH=$PATH:/Users/warrenveerasingam/bin (add this to your bash profile or zsh profile)
  3. Pass -b or — bin parameter with your custom path to install terraform. Ex: tfswitch -b /Users/warrenveerasingam/bin/terraform 0.10.8
  4. Optionally, you can create a .tfswitch.toml file in your terraform directory.
  5. Your .tfswitch.toml file should look like this:
bin = "/Users/warrenveerasingam/bin/terraform"
version = "0.11.3"

Run tfswitch and it should automatically install the required terraform version in the specified binary path

Use .tfswitchrc file

  1. Create a .tfswitchrc file containing the desired version
  2. For example, echo "0.10.5" >> .tfswitchrc for version 0.10.5 of terraform
  3. Run the command tfswitch in the same directory as your .tfswitchrc

Automatically switch with bash

Add the following to the end of your ~/.bashrc file:

builtin cd "$@";
if [ -f "$cdir/.tfswitchrc" ]; then
alias cd='cdtfswitch'

Automatically switch with zsh

Add the following to the end of your ~/.zshrc file:

load-tfswitch() {
local tfswitchrc_path=".tfswitchrc"
if [ -f "$tfswitchrc_path" ]; then
add-zsh-hook chpwd load-tfswitch

NOTE: if you see an error like this: command not found: add-zsh-hook, then you might be on an older version of zsh (see below), or you simply need to load add-zsh-hook by adding this to your .zshrc:

autoload -U add-zsh-hook

Older version of zsh

builtin cd "$@";
if [ -f "$cdir/.tfswitchrc" ]; then

Jenkins setup


echo "Installing tfswitch locally"
chmod 755
./ -b bin-directory



tfswitch lets you install any terraform version on your computer with minimal effort. Rather than installing terraform manually from the source, with tfswitch, you can simply select any version from the dropdown option or provide the desired version as a parameter.

CAUTION: Be cautious of the terraform version that you are using for each project when you switch directories

If you like this project, give us a star here:


Official download page at:

For older versions, you can install it from their release page:

Warren’s Box contains a selection of DevOps tools that are useful for Systems Engineers, DevOps Engineers, and SREs. Most tools are can be easily installed on UNIX based operating systems.



Warren Veerasingam

Software Developer at Pearson.