How to Upgrade Terraform to the Latest Version

Terraform ships a new minor version every few months, and most teams end up running more than one of them at a time. Production stays on a version you trust, while development and staging run ahead of it so you catch breaking changes before your customers do.

tfenv is a version manager for Terraform. It installs multiple Terraform versions side by side on the same machine, switches between them with a single command, and reads a per-project version file so each repository uses the version it expects.

One thing to check before you upgrade: the binary and the state behave differently. You can move the Terraform binary in either direction. Your state file is effectively one-way, because Terraform records the version that last wrote it and an older CLI refuses to run against a newer state.

In this post, you’ll install Terraform and upgrade it to a specific release (for example, 1.13.x, 1.14.x, or 1.15.x) using tfenv. The same commands work for older versions such as 0.12 through 0.15, but target a current 1.x release for anything new.

Staying on an outdated Terraform version means missing out on bug fixes, new language features, and cloud provider support. And in some cases, leaving known security vulnerabilities unpatched. Here’s what you actually gain by keeping Terraform up to date:

• Access to new features and HCL improvements. Each minor release adds language capabilities. Terraform 1.5 introduced import and check blocks. Version 1.6 added terraform test for native testing. Version 1.7 brought removed blocks for decommissioning resources without losing state history. Version 1.10 added ephemeral values, 1.11 added write-only arguments, 1.14 added list resources and the terraform query command, and 1.15 added dynamic module sources, deprecated markers on variables and outputs, and the convert function. If you’re on an older version, you’re writing more code to do less.
• Updated cloud provider support. Terraform’s provider ecosystem evolves alongside AWS, Azure, GCP, and others. While provider versions are managed independently of the Terraform core binary, newer Terraform releases often unlock richer provider functionality — especially around newer resource types and authentication methods.
• Performance improvements. Terraform 1.x has significantly faster plan and apply times compared to the 0.12–0.15 era, particularly for large state files and configurations with deep dependency graphs. Staying behind on versions means slower CI/CD pipelines.
• Security patches. Like any piece of software, Terraform receives CVE fixes and security hardening in newer releases. Running an unpatched Terraform binary in CI/CD or with access to sensitive cloud credentials is a real risk, especially in regulated environments.
• Community and tooling alignment. Tools like Terragrunt, Checkov, Infracost, and Spacelift continually update their support around current Terraform releases. Staying several versions behind can mean incompatibility with the broader IaC tooling ecosystem.

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.

Terraform’s current stable line is 1.15.x. Any 1.16.0-beta or -alpha build on the downloads page is a pre-release and is not for production.

Which target you pick depends on where you’re starting:

• On 1.6 or later. Go straight to the newest 1.15 patch. The v1.x compatibility promises mean you can skip intermediate minor versions.
• On 1.0 through 1.5. Same, but read the upgrade guide for each minor version you cross, and check whether the BUSL license change at 1.6 affects you.
• On anything pre-1.0. Upgrade one minor version at a time: 0.12, 0.13, 0.14, 0.15, then 1.x. Each of those releases had state and syntax migrations that only run in sequence.

Check what you’re on now before you start:

terraform version

Let’s follow the steps below.

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

tfenv is a version manager for Terraform, maintained by the community on GitHub under the MIT License. The current release is v3.2.2. It is not an official HashiCorp tool.

Installing tfenv on MacOS

Let’s first see how to install tfenv on macOS. For macOS, we will use Homebrew. Refer to the following command for installation: 

$ brew install tfenv

Installing tfenv on Linux

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

1. Clone the GitHub repo

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

2. Update $PATH 

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

# zsh
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.zprofile

# fish
echo 'set -x PATH $HOME/.tfenv/bin $PATH' >> ~/.config/fish/config.fish

3. Or symlink the binaries into a directory already on your $PATH. On Ubuntu and Debian, /usr/local/bin needs sudo, so ~/.local/bin is usually easier:

mkdir -p ~/.local/bin
ln -s ~/.tfenv/bin/* ~/.local/bin

Installing tfenv on Windows

tfenv supports Windows 64-bit, but only tests against Git Bash, and it needs symlinks turned on. Enable them before you install:

git config --global core.symlinks true

Outside Git Bash you have two better options. Use WSL and follow the Linux instructions above, or use tenv, which ships as a native binary and works the same way on Windows, Linux, macOS, BSD, and Solaris. See the tenv section below.

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 version, for example tfenv 3.2.2. The exact number doesn’t matter as long as the command succeeds.

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 that 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.

tfenv list-remote returns every release ever published, which is a long list. Pipe it through grep to filter to one release line:

tfenv list-remote | grep '^1\.15\.'

Replace 1.15. with the line you’re targeting. You can also skip the filtering entirely and let tfenv match a pattern at install time:

tfenv install latest:^1\.15\.

To see what you already have installed locally, and which one is active:

tfenv list

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 reads it and picks a version for you:

terraform {
  required_version = "~> 1.15.0"
}

# Install the lowest version the constraint allows
tfenv install min-required

# Install the highest version the constraint allows
tfenv install latest-allowed

Two limits worth knowing. tfenv does not parse full semver ranges: it reads only the first constraint before a comma, so in ">= 1.9, < 2.0" it sees >= 1.9 and ignores the upper bound. And >= resolves to the newest release available, not the newest release inside your range. If you want the newest patch on a specific line, use ~> as above, which resolves to the latest 1.15.x.

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 requires you to first install the version of Terraform you want (if you haven’t already), then switch to that 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

Switching versions by hand doesn’t scale past one project. Drop a .terraform-version file in your repository root and tfenv reads it automatically every time you run Terraform in that directory:

echo "1.15.8" > .terraform-version

To write the file from whatever version you currently have active:

tfenv pin

The file accepts the same values as tfenv use, including latest and latest:<regex>. Commit it. Everyone who clones the repository then gets the same Terraform version without being told, and TFENV_TERRAFORM_VERSION is available as a per-shell override when you need to test something else.

Moving the binary backwards takes one command:

tfenv use 1.14.9

Your state is the harder half. Terraform writes a terraform_version marker into state on every apply, and an older CLI refuses to run against a newer state:

Error: state snapshot was created by Terraform v1.15.8, which is newer
than current v1.14.9; upgrade to Terraform v1.15.8 or greater to work
with this state

The state format itself has been stable since 0.15, so the data is usually readable. It’s the version check that stops you. That leaves three options: upgrade the CLI back to the newer version, restore a state backup taken before the upgrade, or rewrite the version marker with terraform state pull, edit, and terraform state push. Treat the third as a last resort and take a backup first.

This is the real argument for testing an upgrade against a copy of your state before you apply with a new binary in production.

Upgrading the Terraform core binary via tfenv is only half the story. Your configuration also depends on providers (the plugins that communicate with AWS, Azure, GCP, and others), and those need to be upgraded separately.

Terraform locks provider versions in a .terraform.lock.hcl file on the first terraform init run. This ensures consistent versions across your team and CI pipelines, but the lock file won’t update on its own. 

Running terraform init -upgrade tells Terraform to re-evaluate all provider requirements and update the lock file to the latest version that satisfies your constraints:

terraform init -upgrade

It won’t blindly install the latest release of every provider. With a constraint like ~> 5.0, it will upgrade to the latest 5.x release but never jump to 6.0.

After running the command, review the diff in .terraform.lock.hcl before committing. Treat it like any other dependency bump: check the provider changelog, look for breaking changes, and test before merging.

Note: terraform init -upgrade upgrades providers only. To upgrade the Terraform binary itself, use tfenv as described above.

Swapping the binary is the easy part. Making sure your infrastructure survives the change takes more thought. Before upgrading:

1. Read the official upgrade guides for every major version you’re crossing. HashiCorp documents breaking changes in detail — don’t skip this step.
2. Upgrade incrementally. If you’re coming from a pre-1.0 release, don’t jump straight to 1.11. Go 0.12 → 0.13 → 0.14 → 0.15 → 1.x, one step at a time.
3. Test in a non-production workspace first. Run terraform plan against your staging environment with the new version before touching production. Look for warnings — they’re often previews of future breaking changes.
4. Pin your provider versions. Before upgrading Terraform core, lock your provider versions in required_providers so the upgrade doesn’t also silently pull in a new provider version.
5. Use required_version constraints. Add a required_version block to your configuration so that teammates and CI systems can’t accidentally run the wrong Terraform version against your code:

terraform {
  required_version = ">= 1.9, < 2.0"
}

If you’re managing many stacks across teams, tools like Spacelift let you centrally enforce which Terraform version each stack runs — so upgrades become a deliberate, reviewable change rather than a one-off local experiment.

Version management is one problem. Orchestrating the runs themselves is the larger one. Spacelift gives you a GitOps workflow built for infrastructure rather than applications:

• Policy as code — Using Open Policy Agent (OPA), you can control how many approvals a run requires, which resources can be created, what parameters those resources can have, and what happens when a pull request is opened or merged.
• Multi-IaC workflows — Combine Terraform with Kubernetes, Ansible, OpenTofu, Pulumi, and CloudFormation. Create dependencies among them and share outputs across stacks.
• Self-service infrastructure — Use Blueprints to build Golden Paths for your teams. Developers complete a simple form to provision infrastructure based on Terraform and other supported tools — no deep IaC knowledge required.
• Third-party integrations — Integrate your favorite tools and build policies around them. For example, you can embed security tools directly into your workflows using Custom Inputs.
• Drift detection and remediation — Spacelift continuously monitors your environments for discrepancies between live infrastructure and your declared infrastructure as code, and lets you trigger automatic reconciliation to resolve detected drift.

Spacelift also lets you create private workers inside your own infrastructure, so you can execute workflows within your security perimeter. See the documentation for more on configuring private workers.

To learn more about Spacelift, create a free account today or book a demo with one of our engineers.

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.