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
Pin version in
.terraform-version:1.9.8Commit to Git:
git add .terraform-version git commit -m "pin terraform version to 1.9.8"Everyone uses the same version:
git pull tfenv install # Installs version from .terraform-version terraform plan # Uses 1.9.8Upgrade:
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
| Feature | Manual Install | tfenv |
|---|---|---|
| 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
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
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.
