[Demo Webinar] ⛏️ How to build a user-friendly infra self-service portal with Spacelift

➡️ Register Now

Terraform

How to Use tfenv to Manage Multiple Terraform Versions

Using tfenv to Manage Multiple Terraform Versions

🚀 Level Up Your Infrastructure Skills

You focus on building. We’ll keep you updated. Get curated infrastructure insights that help you make smarter decisions.

In this article, we will explore the popular Terraform version manager tfenv, with practical examples of how to install it, and use it to add, change and uninstall different Terraform versions. Tfenv enables you to install multiple Terraform versions and switch between them easily as needed.

What we’ll cover:

  1. Challenges with managing multiple Terraform versions
  2. What is tfenv?
  3. How to install tfenv
  4. How to use tfenv to install, change and uninstall Terraform versions
  5. What is .terraform-version in tfenv?
  6. What is the difference between tfswitch and tfenv?
  7. Tfenv limitations
  8. What is the difference between tenv and tfenv?

Challenges with managing multiple Terraform versions

Different versions of Terraform might be required when working on multiple projects for different customers at the same time, where a particular version is used, or to ensure backward compatibility by running the code with multiple versions. Terraform version upgrades can introduce unwanted problems.

One tip to avoid this is to set the required_version in the Terraform block. When this is set, attempting to run the code with a different version will produce an explicit error, and the code will not run. 

Once you have tested using a different version, the required_version can be updated, effectively ensuring everyone running the code will see the same results.

terraform {
    required_version = "0.12.10"
}

Learn more about how to manage different Terraform versions.

What is tfenv?

tfenv is a version manager for Terraform that allows users to install and switch between multiple Terraform versions easily. It simplifies version control, especially in environments where different projects require different Terraform versions. tfenv ensures compatibility and reduces the risk of using an incorrect Terraform binary by managing versions locally per project or globally. 

It works similarly to tools like pyenv for Python, or rbenv for  Ruby, making it intuitive for developers already familiar with version managers.

How to install tfenv

Here are the steps required to install tfenv on MacOS, Linux, and Windows:

MacOS installation

Using Homebrew run:

brew install tfenv

Note: This won’t work if you have tenv installed because the formulas are conflicting. If you need a package manager that works for both Terraform and OpenTofu, give tenv a try.

Then, verify the installation with:

tfenv --version

Linux installation

Start by cloning the tfenv GitHub repository:

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

Update your shell configuration (~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.tfenv/bin:$PATH"

Then, apply the changes:

source ~/.bashrc  # or source ~/.zshrc

And verify the installation with:

tfenv --version

Windows installation

Currently, tfenv has issues running on Windows. One option is to set up and use the WSL2 (Windows Subsystem for Linux). You can use the steps below to perform a manual installation of tfenv on WSL2 running Ubuntu 20.04:

Clone the repo to your home directory:

git clone --depth=1 https://github.com/tfutils/tfenv.git ~/.tfenv

Add ~/.tfenv/bin to your $PATH:

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

Add a symlink to the tfenv executable:

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

The unzip package will also need to be installed on your system:

apt-get install unzip

Run tfenv to view the available options:

tfenv

How to use tfenv to install, change, and uninstall Terraform versions

Let’s see some examples of how to manage different Terraform versions with tfenv.

1. Install a specific Terraform version

To install a specific Terraform version, run the following:

tfenv install <version>

For example, to install v1.3.9:

tfenv install 1.3.9
tfenv install

2. Set a default Terraform version

To set the version you just installed as your default, run:

tfenv use 1.3.9
tfenv use

Note that any versions set in the environment variable TFENV_TERRAFORM_VERSION or the .terraform-version file already will override this tfenv default. You can write directly to the .terraform-version file using tfenv pin.

3. List installed and available Terraform versions

You can find a list of available Terraform versions here, or directly on the command line using tfenv list-remote.

list remote

You can check your current version in Terraform and in tfenv:

terraform --version
terraform --version
tfenv --version-name
tfenv --version-name

4. Install the latest Terraform version

You can also install the latest available version conveniently using:

tfenv install latest

To install the latest patch of a minor version (e.g., latest 1.6.x):

tfenv install latest:^1.6
  • latest-allowed is a syntax to scan your Terraform files to detect which version is maximally allowed.
  • min-required is a syntax to scan your Terraform files to detect which version is minimally required.

5. Change between installed Terraform versions

To switch and change between your installed Terraform versions, you can first view a list of them:

tfenv list 
tfenv list

Now, to set a global (system-wide) version:

tfenv use 1.2.9
tfenv use 1.2.9

Or to set the latest installed version:

tfenv use latest

You can also set a local version for the current project:

tfenv use 1.2.9 --local

Note that this will create the .terraform-version file.

6. Uninstall a specific Terraform version

To clean a specific Terraform version you no longer need on your system, use the command below:

tfenv uninstall 1.2.9
tfenv uninstall 1.2.9

What is .terraform-version in tfenv?

The .terraform-version file is a plain text file used by tfenv to determine which Terraform version to use in a specific project directory. It contains a single line specifying the desired Terraform version, for example:

1.6.6

To use it, create the file in your Terraform project root:

echo "1.6.6" > .terraform-version

When you run any terraform command in this directory, tfenv looks for the .terraform-version file. If it’s found, tfenv ensures the specified version is selected.

If the version is not yet installed, you’ll see a message like:

tfenv: version '1.6.6' is not installed

To install the missing version, run:

tfenv install 1.6.6

Note: It’s recommended that you commit .terraform-version to version control to ensure consistent environments across your team.

What is the difference between tfswitch and tfenv?

tfswitch and tfenv are both version management tools for Terraform. 

Tfswitch is a CLI utility that quickly switches between Terraform versions by reading version constraints from .terraform-version or .tfswitchrc, focusing on ease of use and automation. 

Tfenv, inspired by rbenv, is a more customizable version manager that allows you to install, manage, and switch between versions locally or globally using shell commands.

Tfenv gives more control over environment-specific setups, while tfswitch prioritizes quick switching based on project configuration files. Both support installing specific Terraform versions, but tfenv has a stronger focus on shell integration and environment management.

Tfenv limitations

While tfenv is generally reliable, here are the main points to be aware of:

  1. Not officially maintained by HashiCorp – tfenv is a community tool, so future Terraform changes may break compatibility without warning.
  2. Limited native support on Windows – It works best on Unix-like systems and may require WSL for use on Windows.
  3. Dependent on external URLs for downloads – It pulls binaries from HashiCorp or GitHub, which can fail due to API changes or rate limits.
  4. Does not manage provider plugin versions – tfenv only switches the core Terraform binary, not individual provider versions.
  5. Requires manual updates – You need to update tfenv manually to support new Terraform versions or features.

What is the difference between tenv and tfenv?

Tenv is a versatile version manager that supports multiple HashiCorp tools, including Terraform, Terragrunt, and OpenTofu, providing a unified interface for managing various infrastructure tools. 

Tfenv, on the other hand, focuses specifically on Terraform version management and offers deep shell integration with local and global version-switching capabilities. 

Tenv emphasizes cross-tool compatibility and simplicity, while tfenv provides more granular control over Terraform-specific environments and configurations.

Managing Terraform Resources with Spacelift

Terraform is really powerful, but to achieve an end-to-end secure Gitops approach, you need to use a product that can run your Terraform workflows. Spacelift takes managing Terraform to the next level by giving you access to a powerful CI/CD workflow and unlocking features such as:

  • Policies (based on Open Policy Agent) – You can control how many approvals you need for runs, what kind of resources you can create, and what kind of parameters these resources can have, and you can also control the behavior when a pull request is open or merged.
  • Multi-IaC workflows – Combine Terraform with Kubernetes, Ansible, and other infrastructure-as-code (IaC) tools such as OpenTofu, Pulumi, and CloudFormation,  create dependencies among them, and share outputs
  • Build self-service infrastructure – You can use Blueprints to build self-service infrastructure; simply complete a form to provision infrastructure based on Terraform and other supported tools.
  • Integrations with any third-party tools – You can integrate with your favorite third-party tools and even build policies for them. For example, see how to integrate security tools in your workflows using Custom Inputs.
affinity logo white

Previously, the Affinity team used Terraform both as their runner and for state management. Now, they use Amazon S3 for state management, but because this is connected to the Spacelift provider, state management is something they don’t have to worry about.

Spacelift customer case study

Read the full story

Spacelift enables you to create private workers inside your infrastructure, which helps you execute Spacelift-related workflows on your end. Read the documentation for more information on configuring private workers.

You can check it out for free by creating a trial account or booking a demo with one of our engineers.

Key points

Tfenv is a simple-to-use open-source command line program that enables you to manage and switch between multiple versions of Terraform. Check out the tfenv repo on Github for more information.

If you’re managing multiple Terraform projects with different version requirements, tfenv is still a lightweight and effective tool, but consider its limitations for CI/CD, Windows devs, or tightly controlled environments.

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

Achieve Terraform at scale with Spacelift

Spacelift takes managing infrastructure at scale to a whole new level, offering a more open, more customizable, and more extensible product. It’s a better, more flexible CI/CD for Terraform, offering maximum security without sacrificing functionality.

Learn more

The Infrastructure Automation

Report 2025

Our research shows that teams are overconfident

and race toward faster deployments,

sacrificing governance and falling into

the Speed-Control Paradox.

Get the Report
Bottom overlay - The Infrastructure Automation Report