Managing multiple Terraform versions can become challenging when different infrastructure projects depend on different releases. Fortunately, tfenv project-specific versions make it possible to use the appropriate Terraform version for each project without constantly switching versions manually.
In this guide, we’ll explain how tfenv handles project-specific Terraform versions, how to use .terraform-version, and why version pinning is useful for reliable infrastructure development.
What Is tfenv?
tfenv is a Terraform version manager that allows developers and DevOps teams to install, manage, and switch between multiple Terraform versions on the same machine.
Instead of installing Terraform manually and replacing the binary whenever a project requires another version, tfenv provides commands for installing and selecting versions as needed.
For example:
tfenv install 1.9.5
tfenv use 1.9.5
This is particularly useful when working with multiple infrastructure repositories that have different Terraform requirements.
Does tfenv Support Project-Specific Versions?
Yes, tfenv supports project-specific Terraform versions.
The recommended way to specify a Terraform version for a particular project is to create a file named:
.terraform-version
in the project’s root directory.
For example:
my-infrastructure/
├── .terraform-version
├── main.tf
├── variables.tf
└── outputs.tf
The .terraform-version file can contain the Terraform version required by the project:
1.9.5
When you work inside that directory, tfenv can use the version specified by the file.
This approach allows every project to define its own Terraform version without affecting other projects on the same machine.
How to Set a Project-Specific Terraform Version with tfenv
Setting up a project-specific version is straightforward.
Step 1: Create a .terraform-version File
Navigate to your Terraform project:
cd my-infrastructure
Create the version file:
echo "1.9.5" > .terraform-version
The file should contain the exact Terraform version you want the project to use.
Step 2: Install the Required Version
If the version isn’t already installed, run:
tfenv install
tfenv reads the .terraform-version file and installs the specified version.
You can also install a version directly:
tfenv install 1.9.5
Step 3: Verify the Terraform Version
Run:
terraform version
You should see the version specified by your project.
You can also check which Terraform executable is being used:
which terraform
Why Use Project-Specific Terraform Versions?
Using tfenv project-specific versions provides several benefits for teams managing infrastructure with Terraform.
1. Avoid Version Conflicts
Different projects may depend on different Terraform releases. For example:
- Project A may require Terraform 1.7.x
- Project B may require Terraform 1.8.x
- Project C may require Terraform 1.9.x
With .terraform-version, each project can specify its required version independently.
2. Improve Reproducibility
Pinning a Terraform version helps ensure that developers and CI/CD environments use the same Terraform release.
This can reduce unexpected differences caused by running different Terraform versions across environments.
3. Simplify Team Collaboration
Instead of telling every developer which Terraform version to install, the required version can be stored directly in the repository:
.terraform-version
Anyone using tfenv can then install the appropriate version with:
tfenv install
4. Make Version Upgrades Safer
Terraform upgrades can introduce behavior changes, provider compatibility issues, or configuration differences.
Project-specific versioning lets teams upgrade one project at a time instead of changing Terraform versions globally.
Can Different Projects Use Different Terraform Versions?
Yes.
For example, suppose you have two projects:
terraform-project-a/
└── .terraform-version
with:
1.7.5
and:
terraform-project-b/
└── .terraform-version
with:
1.9.5
When working in Project A, tfenv can select Terraform 1.7.5. When you move to Project B, tfenv can select Terraform 1.9.5.
This makes tfenv particularly useful for engineers who maintain multiple Terraform codebases.
.terraform-version vs tfenv use
There are two common ways to select a Terraform version.
The first is to explicitly select a version:
tfenv use 1.9.5
This changes the version selected by tfenv.
The second is to define the version in the project:
.terraform-version
The second approach is generally better for project-specific version management because the version requirement is stored alongside the Terraform configuration.
For teams, committing .terraform-version to source control can make the expected Terraform version visible to everyone working on the project.
Should .terraform-version Be Committed to Git?
In most projects, yes.
If the file represents the Terraform version required by the repository, committing it allows developers and automation environments to use the same versioning convention.
For example:
git add .terraform-version
git commit -m "Pin Terraform version"
Your repository then clearly communicates its Terraform version requirement.
However, teams should still make sure their CI/CD systems explicitly install or validate the required Terraform version rather than assuming that every environment has tfenv installed.
tfenv and Terraform Version Constraints Are Not the Same Thing
It’s important to distinguish between tfenv’s version selection and Terraform’s own version constraints.
A Terraform configuration can specify supported Terraform versions using the required_version argument:
terraform {
required_version = ">= 1.8.0, < 2.0.0"
}
This tells Terraform which versions are acceptable for the configuration.
Meanwhile, .terraform-version tells tfenv which specific version to select for the project.
For example:
.terraform-version
1.9.5
and:
terraform {
required_version = ">= 1.8.0, < 2.0.0"
}
work well together: the project allows a range of versions, while the development environment pins a particular version.
Best Practices for tfenv Project-Specific Versions
When using tfenv across multiple Terraform projects, consider these best practices.
Pin a Known Terraform Version
Avoid relying on whatever Terraform version happens to be installed globally. Define a specific version in .terraform-version.
Commit the Version File
Store .terraform-version in source control when it represents a project requirement.
Match Terraform Configuration Constraints
Make sure the version specified in .terraform-version satisfies the project’s required_version constraint.
Keep CI/CD Consistent
If your local development environment uses tfenv, make sure CI/CD also uses a controlled Terraform version.
Test Terraform Upgrades
Before changing the version in .terraform-version, run your Terraform validation, planning, testing, and deployment workflows.
Frequently Asked Questions
Does tfenv automatically detect .terraform-version?
Yes. tfenv is designed to use a .terraform-version file to determine the Terraform version for a directory and its project context.
Can every Terraform project have a different version?
Yes. Each project can contain its own .terraform-version file with the required Terraform release.
Do I need to install every Terraform version manually?
No. You can use:
tfenv install
when a project’s .terraform-version specifies the version to install.
Is .terraform-version specific to Terraform?
It is a tfenv convention for selecting the Terraform version. Terraform itself does not use this file to enforce version requirements.
Should I use .terraform-version with required_version?
Yes. They serve different purposes and can complement each other. .terraform-version selects the version used by tfenv, while required_version defines which Terraform versions the configuration supports.
Conclusion
Tfenv project-specific versions provide a simple and effective way to manage multiple Terraform releases across different infrastructure projects. By placing a .terraform-version file in each project, teams can define the Terraform version they expect to use without manually switching versions every time they move between repositories.
For reliable Terraform workflows, combine project-specific version management with Terraform’s required_version constraint, source-control practices, and consistent CI/CD configuration. This approach makes Terraform environments more predictable, reproducible, and easier to maintain.