Managing Multiple Terraform Versions Without Losing Your Mind 🧠✨

Ever opened a project, ran terraform apply, and immediately watched your state file blow up because your local machine was running a newer binary than your team’s codebase?

Yeah. The absolute worst.

When you bounce between repositories or test upcoming releases, managing conflicting Terraform versions manually is an executive dysfunction nightmare.

Here is how to set up your machine so managing versions takes zero mental bandwidth.

The Three Ways People Solve This

1. Docker Containers: Run Terraform inside a container for every repo. The tax: You have to maintain Dockerfiles, volume mounts, and shell aliases. High cognitive overhead.

2. tfenv (The “Set-and-Forget” Path): Swaps versions silently in the background whenever you cd into a directory with a .terraform-version file. Best for: People who want the machine to do the thinking automatically.

3. tfswitch (The Interactive Menu Path): An interactive prompt that scans your code and lets you pick or install versions with your arrow keys. Best for: People who love visual cues, want zero extra config files, or work in repos that only define constraints inside versions.tf.

Let’s break down both options so you can pick your flavor.

Prerequisite: Clean Slate (Do This First!)

Before installing either tool, unlink or remove any standalone Terraform binary so your system doesn’t get confused about which one has terminal priority:

# Option A: Just unlink it (keeps files around safely)
brew unlink terraform

# Option B: Remove it completely (cleaner)
brew remove terraform

Option A: tfenv (Automatic Background Switching)

tfenv is designed for folks who want zero prompts and zero friction once it’s configured.

Install tfenv

brew install tfenv

Download the Versions You Need

1. Grab an older pinned version tfenv install 1.5.7

2. Grab the latest stable release tfenv install latest

3. Check what you currently have installed tfenv list

Automate It via Config Files

Create a global fallback in your home directory, plus project-specific overrides.

1. Create a global fallback in your home directory echo "1.5.7" > ~/.terraform-version

2. Create project-specific version overrides cd ~/code/my-project echo "latest" > .terraform-version

Whenever you jump into ~/code/my-project, running terraform version will automatically use that project’s release—no extra commands required.

If you ever pull a colleague’s branch that requires a version you haven’t downloaded yet, just run: tfenv install

Option B: tfswitch (The Visual & Interactive Hero)

If you prefer an interactive menu where you can arrow through versions, or you hate managing extra .terraform-version files, tfswitch is fantastic. It can inspect your existing .tf files (like required_version = “~> 1.6.0” inside versions.tf), detect what you need, and prompt you directly.

1. Install tfswitch brew install warrensbox/tap/tfswitch

   

2. Run It Interactively Whenever you are in a repo, simply type: tfswitch

   If you have a versions.tf or .tfswitchrc file, it detects the constraint and switches immediately.

   If not, it opens a clean dropdown list right in your terminal. Use your arrow keys, hit Enter, and it downloads and activates that version on the fly.

   

3. Quick Non-Interactive Switches You can also pass arguments directly:

   # Switch directly to a specific version
   tfswitch 1.5.7
   # Switch to the latest release
   tfswitch -u
   

⚡ Quick Cheat Sheet: Which One Fits Your Brain?