Q: How do you manage multiple versions of Terraform itself in your team?
To manage multiple versions of Terraform in a team, declare a supported range in required_version, pin one exact version per repo with a version manager such as tfenv, and run the same pinned binary in CI.
Want to master this scenario in a live sandbox? KodeKloud's HashiCorp Certified Terraform Associate (003) Interactive Labs covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>manage multiple versions of Terraform</strong> in a team, declare a supported range in <code>required_version</code>, pin one exact version per repo with a version manager such as tfenv, and run the same pinned binary in CI. Interviewers ask this because Terraform state is forward-only: once a newer binary writes the state, older binaries refuse to read it, so one engineer running a different version can block everyone. A strong answer covers local tooling, the constraint in code, CI enforcement, and a controlled upgrade process for many root modules.
Mental model: required_version versus the binary you run
Terraform has three independent version axes, and confusing them is the most common source of team friction.
terraform {
required_version = ">= 1.6.0, < 1.9.0" # supported window for this repo
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.40"
}
}
}
- Core version: the
terraformbinary itself. Check it withterraform version. It decides which language features (import blocks,movedblocks,removedblocks) are available. - required_version: a constraint inside the
terraform {}block that makesinit,planandapplyfail fast when the binary is outside the allowed range. It documents intent but does not install anything. - Provider versions: pinned separately in
required_providersand recorded in.terraform.lock.hcl. Upgrading core does not upgrade providers, and the reverse is also true. - State format version: the state file records the Terraform version that last wrote it. A newer writer can make the state unreadable for older binaries, which is why unsynchronised upgrades hurt teams.
Hands-on: manage multiple versions of Terraform with tfenv
A version manager lets each repository declare its exact version and switches the binary automatically when you change directories.
# One-time per repo
echo "1.7.5" > .terraform-version
tfenv install # installs the version in .terraform-version
tfenv use 1.7.5
terraform version # Terraform v1.7.5 on darwin_arm64
# Several root modules on different versions
tfenv list # shows installed versions, * marks active
cd ../legacy-network && tfenv use 1.5.7
- tfenv: reads a
.terraform-versionfile in the repo root.tfenv installwith no argument installs the version in that file, andtfenv useactivates it. - Constraint-driven selection:
tfenv install min-requiredandtfenv use min-requiredpick the lowest version that satisfiesrequired_version, which is useful for verifying that your minimum is real. - Alternatives:
asdfandmise(read.tool-versions) manage Terraform alongside kubectl, helm and others, so one file pins the whole toolchain. OpenTofu has its own manager,tofuenv. - Commit the file: check
.terraform-versioninto git so a fresh clone and a CI runner resolve the same version without any wiki page.
Pin the same Terraform version in CI
Local discipline is not enough; the pipeline must be the source of truth and must fail when it drifts from the repo.
# .github/workflows/terraform.yml (excerpt)
- name: Read pinned version
id: tf
run: echo "version=$(cat .terraform-version)" >> "$GITHUB_OUTPUT"
- uses: hashicorp/setup-terraform@v3
with:
terraform_version: ${{ steps.tf.outputs.version }}
- name: Verify binary matches pin
run: |
test "$(terraform version -json | jq -r .terraform_version)" = "$(cat .terraform-version)"
- GitHub Actions:
hashicorp/setup-terraformacceptsterraform_version(an exact version or a constraint). Feed it the contents of.terraform-versionso the file stays authoritative. - Containers: run Terraform from a pinned image tag, never
latest, and bump the tag in the same PR that bumps the version file. - HCP Terraform or Terraform Enterprise: each workspace has its own Terraform version setting. Keep it in sync with the repo, or manage it as code with the
tfeprovider. - Guard step: add a job step that compares
terraform version -jsonagainst the version file and fails with a clear message instead of a confusing state error later.
Failure modes: state written by a newer version
Most incidents here are one engineer applying with a newer binary and everyone else being locked out of the state.
- Symptom: an error similar to state snapshot was created by Terraform vX, which is newer than current vY. The fix is to upgrade your binary, not to edit the state file.
- Downgrade is not supported: after a newer version writes state you generally cannot roll back to the older binary. Restore from a versioned backend object only if you accept losing the changes made since.
- Mixed modules: a child module may declare its own
required_version. The strictest constraint across the whole tree wins, so a vendored module can silently raise your floor. - Licensing and forks: Terraform 1.6 and later is under the BUSL license, and OpenTofu is a separate fork whose versions do not map one-to-one. Do not mix
terraformandtofuagainst the same state without an explicit migration plan.
Production practice: a controlled upgrade workflow
Treat a Terraform core bump like a dependency upgrade with a blast radius, not like a laptop preference.
- Read the changelog: check the upgrade guide for deprecations between your current and target minor versions before touching any repo.
- Prove it with a plan: in a branch, bump the version file and
required_version, runterraform init -upgrade=falseandterraform planfor every root module. The goal is a no-op plan; any diff is a finding to explain. - Roll out in tiers: upgrade dev, then staging, then prod roots, and only raise
required_version's lower bound once every environment has applied successfully. - Automate nudges: Renovate or Dependabot can open PRs for the version file and for pinned CI actions, so upgrades are small and routine.
- I pin Terraform with a <code>required_version</code> range in code and an exact version in <code>.terraform-version</code>, installed through tfenv or mise.
- CI installs the same version from that file and fails if <code>terraform version</code> differs, so local and pipeline runs are identical.
- Upgrades go through a PR with no-op plans on every root module, rolled out dev to prod, with state versioning enabled as a safety net.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Setting <code>required_version = ">= 1.0"</code> and nothing else An open-ended floor lets every engineer and runner use a different minor version, and the newest one that writes state locks out the rest.
- Using the <code>latest</code> tag for the Terraform container or action in CI The pipeline silently upgrades core, and the first apply after a release can rewrite state in a version nobody tested.
- Trying to downgrade after a newer version has applied State written by a newer release is generally unreadable by older ones; the recovery path is a state backup, not a binary swap.
- Assuming a core upgrade also upgrades providers Providers are locked in <code>.terraform.lock.hcl</code>; changing core without reviewing provider pins gives you two unrelated upgrade axes to debug at once.