How to Upgrade Terraform to a Specific Version Using tfenv

Introduction

Upgrading Terraform to a specific version, especially when you’re not ready to jump to the latest release, can seem challenging at first. This guide provides a clear pathway for users who need to manage multiple versions of Terraform, particularly when a precise upgrade path is required for compatibility or testing purposes. Let’s dive into how you can upgrade Terraform to a specific version, such as from v0.11.13 to v0.11.14, before considering a major upgrade to v0.12.0 or beyond.

The Challenge

For many users, the default upgrade path using package managers like Homebrew on macOS may not offer the control needed for incremental upgrades. Directly upgrading to the latest version (e.g., from v0.11.13 to v0.12.0) might introduce changes that require significant adjustments to your Terraform configurations. The goal here is to achieve a controlled upgrade to v0.11.14, ensuring compatibility and stability before making a larger version leap.

The Solution: tfenv

Enter tfenv, a Terraform version manager that simplifies the process of managing multiple Terraform versions. It offers a seamless way to switch between versions and is particularly useful in scenarios where incremental upgrades are necessary. Here’s how to use tfenv to upgrade Terraform to a specific version on macOS:

Step 1: Installing tfenv

First, if you haven’t already installed tfenv, you can do so using Homebrew:

brew install tfenv

Step 2: Listing Available Versions

Before deciding on the version to upgrade to, you might want to see a list of available versions. This can be done with:

tfenv list-remote

This command displays all available Terraform versions, helping you identify the specific version you need.

Step 3: Installing a Specific Version

Once you’ve decided on the version (e.g., v0.11.14), you can install it using:

tfenv install 0.11.14

tfenv will fetch and install the specified Terraform version, making it the active version on your system.

Step 4: Switching Between Versions

If you ever need to switch to another version, tfenv makes it easy:

tfenv use 0.12.0

This command switches the active Terraform version to v0.12.0.

Additional Tips

• Automatic Version Switching: By adding a .terraform-version file to your project directory with the desired version number, tfenv can automatically switch to the correct Terraform version for that project.
• Troubleshooting: If you encounter errors related to provider plugins or versions, ensure that your Terraform configurations are compatible with the version you’re switching to.
• Unlinking Previous Versions: If you’ve installed Terraform via Homebrew and encounter conflicts, you may need to unlink Terraform before using tfenv:

brew unlink terraform

Alternative: Manual Installation (Without tfenv)

# Download a specific version directly
TERRAFORM_VERSION="1.8.5"
wget "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip"
unzip "terraform_${TERRAFORM_VERSION}_linux_amd64.zip"
sudo mv terraform /usr/local/bin/
terraform version

Upgrade Checklist

Before upgrading Terraform versions, follow this process:

# 1. Check current version
terraform version

# 2. Review the changelog for breaking changes
# https://github.com/hashicorp/terraform/blob/main/CHANGELOG.md

# 3. Back up your state
terraform state pull > backup-$(date +%Y%m%d).tfstate

# 4. Install the new version
tfenv install 1.8.5
tfenv use 1.8.5

# 5. Initialize with the new version
terraform init -upgrade

# 6. Run plan to check for issues
terraform plan

# 7. Pin the version in your project
echo "1.8.5" > .terraform-version

Version Constraint Best Practices

terraform {
  # Pin to minor version — allows patch updates
  required_version = "~> 1.8.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

Common tfenv Commands

Related Articles

• Fix Inconsistent Dependency Lock File
• Terraform Version Constraints Guide
• Install Terraform on Ubuntu
• Terraform Glossary

Conclusion

Use tfenv to manage multiple Terraform versions — install, switch, and pin versions per project with .terraform-version files. Always back up state before upgrading, check changelogs for breaking changes, and pin required_version in your configuration to keep your team aligned.