TerraformPilot

DevOps

Install Terraform with tfenv: Manage Multiple Terraform Versions

Install and manage multiple Terraform versions with tfenv. Switch between versions per project, auto-detect from .terraform-version files

LLuca Berton1 min read

tfenv is a Terraform version manager — like nvm for Node.js or pyenv for Python. It lets you install multiple Terraform versions and switch between them per project. Essential when you maintain projects on different Terraform versions.

Why tfenv?

#

Without tfenv:

# Project A needs Terraform 1.7
# Project B needs Terraform 1.10
# You can only have one version installed
terraform version  # 1.10.0 — Project A breaks

With tfenv:

cd project-a/
terraform version  # 1.7.5 (auto-detected from .terraform-version)
 
cd project-b/
terraform version  # 1.10.0 (auto-detected from .terraform-version)

Install tfenv

#

macOS (Homebrew)

# 
brew install tfenv

Linux (Git Clone)

# 
git clone https://github.com/tfutils/tfenv.git ~/.tfenv
 
# Add to PATH
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify

# 
tfenv --version
# tfenv 3.0.0-37-g0494129

Basic Usage

#

List Available Versions

# 
tfenv list-remote
# 1.10.0
# 1.9.8
# 1.9.7
# ...
# 1.0.0

Install a Version

# 
# Install specific version
tfenv install 1.10.0
 
# Install latest
tfenv install latest
 
# Install latest 1.9.x
tfenv install latest:^1.9

Switch Versions

# 
# Set global default
tfenv use 1.10.0
 
# Verify
terraform version
# Terraform v1.10.0

List Installed Versions

# 
tfenv list
#   1.10.0
#   1.9.8
# * 1.7.5 (set by /home/user/project/.terraform-version)

Per-Project Version Pinning

#

Create a .terraform-version file in your project root:

echo "1.9.8" > .terraform-version

Now terraform automatically uses that version in this directory:

cd my-project/
cat .terraform-version
# 1.9.8
 
terraform version
# Terraform v1.9.8
 
cd ../other-project/
cat .terraform-version
# 1.10.0
 
terraform version
# Terraform v1.10.0

Auto-Install Missing Versions

# 
# In ~/.tfenv/settings or export:
export TFENV_AUTO_INSTALL=true
 
# Now when you cd into a project with .terraform-version,
# tfenv automatically installs that version if missing

CI/CD Integration

#

GitLab CI

# 
before_script:
  - git clone https://github.com/tfutils/tfenv.git ~/.tfenv
  - export PATH="$HOME/.tfenv/bin:$PATH"
  - tfenv install    # Reads .terraform-version
  - terraform version
 
plan:
  script:
    - terraform init
    - terraform plan

GitHub Actions

# 
- name: Setup tfenv
  run: |
    git clone https://github.com/tfutils/tfenv.git ~/.tfenv
    echo "$HOME/.tfenv/bin" >> $GITHUB_PATH
 
- name: Install Terraform
  run: tfenv install  # Uses .terraform-version
 
- name: Plan
  run: |
    terraform init
    terraform plan

Docker

# 
FROM ubuntu:24.04
 
RUN apt-get update && apt-get install -y git curl unzip
 
RUN git clone https://github.com/tfutils/tfenv.git /root/.tfenv
ENV PATH="/root/.tfenv/bin:${PATH}"
 
COPY .terraform-version .
RUN tfenv install
 
ENTRYPOINT ["terraform"]

Team Workflow

#

  1. Pin version in .terraform-version:

    1.9.8

  2. Commit to Git:

    git add .terraform-version
git commit -m "pin terraform version to 1.9.8"

  3. Everyone uses the same version:

    git pull
tfenv install    # Installs version from .terraform-version
terraform plan   # Uses 1.9.8

  4. Upgrade:

    echo "1.10.0" > .terraform-version
tfenv install 1.10.0
terraform init -upgrade
terraform plan   # Test with new version
git add .terraform-version
git commit -m "upgrade terraform to 1.10.0"

Useful Commands

# 
# Install and switch in one step
tfenv install 1.10.0 && tfenv use 1.10.0
 
# Uninstall a version
tfenv uninstall 1.7.5
 
# Install latest minor of a major
tfenv install latest:^1.9
 
# Pin latest to project
tfenv use latest
terraform version | head -1 | awk '{print $2}' | tr -d 'v' > .terraform-version

tfenv vs Manual Installation

#
FeatureManual Installtfenv
Multiple versions❌ One at a time✅ Install many
Per-project version❌ Global only✅ .terraform-version
Team consistency❌ Hope everyone matches✅ Pinned in Git
Version switching❌ Re-download binary✅ tfenv use X
CI/CD❌ Hardcode in pipeline✅ Reads .terraform-version

Hands-On Courses

#

Conclusion

#

tfenv eliminates "works on my machine" version conflicts. Install it, add .terraform-version to your projects, commit to Git, and every team member automatically uses the same Terraform version. It takes 2 minutes to set up and prevents hours of debugging version-related issues.

#Terraform#DevOps#Installation#tfenv

Share this article

Related articles