How to Upgrade Terraform to the Latest Version

Just like a versioning tool such as Git or SVN, which allows you to rollback or upgrade if there is a problem with the current version of your code, tfenv lets you upgrade as well as rollback versions of Terraform. 

But why do we need multiple versions of Terraform? A typical infrastructure setup always consists of development, testing, staging, and the production environment. As a rule of thumb, the production environment gets the most stable version. On the other hand, development, test, and sometimes staging environments receive newer versions of any software package. The same goes for Terraform. 

If during the testing phase there is a bug which breaks the existing infrastructure setup, tfenv can help roll back Terraform to the previous stable version. Similarly, you can upgrade to the next stable version so that your Terraform stack is up to date.

In this post, we’ll see how you can install Terraform and upgrade it to a specific release (for example, Terraform 1.11.x, 1.12.x, or 1.14.x) using tfenv. The commands work the same way for older versions such as 0.12–0.15, but we strongly recommend targeting a recent 1.x release for new projects.

Note: Newer Terraform versions (starting in the 1.5.x timeframe) are released under HashiCorp’s Business Source License (BUSL), which comes with additional restrictions for some commercial use cases. If you prefer a community-governed, truly open-source option, OpenTofu is a fork of Terraform 1.5.6 maintained under the Linux Foundation, and it is largely compatible with existing Terraform workflows. Spacelift supports both Terraform and OpenTofu, so the tfenv/Terraform upgrades covered in this post fit neatly into your broader IaC strategy either way.

Before we go into the installation part of tfenv let’s first see what tfenv is.

tfenv is a versioning tool for Terraform, maintained by the open source community on Github, under the MIT Open source license. Keep in mind it is not an official tool by HashiCorp.

Installing tfenv on MacOS

Lets first see how we can install tfenv on MacOS. For MacOS we are going to use the brew package manager. Refer to the following command for installation: 

$ brew install tfenv

Installing tfenv on Linux

Installing on Linux is a bit more manual. Use the following installation instructions:

1: Clone the GitHub repo

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

2: Update $PATH 

$ echo ‘export PATH=”$HOME/.tfenv/bin:$PATH”‘ >> ~/.bash_profile

3: Create a symlinks

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

Installing tfenv on Windows

tfenv officially lists Windows (64-bit) support, but it’s only tested in Git Bash and may still run into symlink issues. In practice, most teams either use WSL (Windows Subsystem for Linux) and follow the Linux instructions, or manage Terraform versions via other tooling on Windows and reserve tfenv for macOS/Linux build agents.

If you try tfenv on native Windows Git Bash, be prepared for occasional rough edges.

Verify tfenv installation

Whether you are on MacOS or Linux, you can verify the installation of tfenv by simply running the following command:

$ tfenv -v

It should print a tfenv version, for example tfenv 3.0.0 or similar. The exact number isn’t important, as long as the command succeeds without errors.

If you want to check the latest tfenv release, you can always look at the GitHub releases page.

Now that we have seen how to install tfenv, let’s dig into the tfenv commands. The first command which we are going to see is

 $ tfenv list-remote

The above command will list out all available versions of Terraform to date. Here’s a screenshot after running the tfenv list-remote command.

If you are looking for a specific version of Terraform (e.g. v0.12, v0.13, v0.14, v0.15) but tfenv list-remote returns with a really long list of versions, you can run the following command that includes the version you want.

If you’re looking for a specific major/minor line, you can pipe the output through grep. For example, to find the 0.12.0 release:

tfenv list-remote | grep 0.12.0

Replace 0.12.0 with the major/minor you’re targeting (for example 1.13. or 1.10.).

You have seen in the previous steps how to install tfenv and how to list all or some specific version of Terraform. 

Let’s install a specific version (0.12.0) of Terraform using tfenv. Use the following tfenv for installation: 

$ tfenv install 0.12.0

After installing Terraform 0.12.0, you need to run one more command to actually use that version:

$ tfenv use 0.12.0

Verify the installation of Terraform by running

$ terraform -v 

Note: the above-mentioned command can be used for any version of Terraform , e.g. 0.13.0, 0.14.0, 0.15.0

Use version constraints with tfenv

If your configuration has a terraform block with required_version, tfenv can read that and choose an appropriate version automatically. For example:

terraform {
required_version = ">= 1.5, < 1.15"
}

You can then let tfenv pick a version that satisfies this constraint:

# Install the minimum required version
tfenv install min-required

# Install the latest allowed version
tfenv install latest-allowed

This makes it much easier to keep multiple projects on compatible versions without hard-coding a specific Terraform release everywhere.

In the previous step we saw how to upgrade to a specific version of Terraform, but what if you want to upgrade to the latest version irrespective of any specific one?

Well, tfenv provides the latest flag which can be used along with the $ tfenv install command and it will let you install the latest stable version of Terraform.

Here is the tfenv command for installing the latest version of Terraform (as of writing this article): 

$ tfenv install latest

To switch and use the latest version of Terraform, run: 

$ tfenv use 1.0.8

Verify the installation by running the $ terraform -v command:

In the previous steps we have seen how to install specific versions (0.12.0) as well as the latest version of Terraform.

Let’s now see how to install and switch to some other version, 0.13.0 for example.

tfenv always mandates you to first install the version (if you have not installed before) of Terraform which you want to have, and then to make the switch to that specific version.

First, install Terraform version 0.13.0:

$ tfenv install 0.13.0

Then, make the switch to 0.13.0 (if you have already installed other versions of Terraform, you can make direct use of the tfenv use command):

$ tfenv use 0.13.0

Note: the above-mentioned steps can be used for switching to any desired version of Terraform. Learn more about how to manage different Terraform versions.

Last but not least, tfenv provides you with a feature to uninstall any version of Terraform. To uninstall any version of Terraform, you must provide the exact version (e.g. latest, 0.15.0, 0.14.0 etc.).

Here’s how to uninstall the latest version of Terraform:

$ tfenv uninstall latest

To uninstall a specific version of Terraform, such as 0.12.0, run

$ tfenv uninstall 0.12.0

Software is released in different cycles, and new versions usually add new features, bug fixes, security vulnerability fixes, and more. The same goes for Terraform – each new version of Terraform introduces a variety of new features, enhancements, and performance improvements, ensuring that users have access to the latest tools and capabilities for managing their infrastructure.

These updates can lead to better configurations, thanks to improvements of HCL, and faster plan and apply times that enhance the productivity of infrastructure teams. Additionally, newer versions of Terraform include updates to support the latest services and features from cloud providers, allowing users to leverage the most current cloud capabilities. Newer versions also receive important security updates, protecting users from known vulnerabilities and ensuring the integrity of their infrastructure.

How to plan a safe Terraform upgrade

Switching binaries is easy; making sure your infrastructure survives the change is the harder part. Before you move to a newer Terraform version:

1. Read the official upgrade guide(s) for each major version you’re crossing and check for breaking changes
2. Upgrade incrementally (for example 0.12 → 0.13 → 0.14 → 0.15 → 1.x), especially if you’re coming from pre-1.0 releases.
3. Test in a non-production workspace first, using the same Terraform version and provider versions you intend to run in production
4. Use tfenv install min-required / latest-allowed to respect your existing required_version constraints when testing

Tools like Spacelift can help you run these tests as pull-request plans, so upgrades are reviewed and repeatable instead of being one-off local experiments.

tfenv is a great tool to utilize when you are managing multiple environments that might have different versions of Terraform. With the help of tfenv, you can try out as well as install different versions of Terraform, and with the tfenv use command you can easily switch between the various versions of Terraform. 

In addition to tfenv, Spacelift lets you centrally manage which Terraform or OpenTofu version each stack uses, enforce version policies, and roll out upgrades safely across all your environments. If you need help managing Terraform/OpenTofu at scale – including complex workflows, policy as code, drift detection, and per-run cloud credentials – Spacelift is built for that. You can test drive it for FREE, by going here and creating a trial account.