Tfenv for clean, predictable Terraform version control.A lightweight way to install, switch, and pin Terraform versions across teams, local environments, and CI/CD pipelines.
Keep every project aligned with the right Terraform CLI version, reduce setup friction, and make your infrastructure workflow feel faster, cleaner, and more reliable.
One version file. The right Terraform CLI for every project.
A specialized version manager built specifically for the Terraform CLI.
Tfenv solves the critical challenge of version drift in Infrastructure as Code by reading the version pin from your repository, downloading the matching HashiCorp-signed Terraform binary, and shimming it onto your PATH automatically. No more manual tarballs or version guesswork.
It supports macOS and Linux, with Windows workflows documented for Git Bash. This guarantees your onboarding documentation, CI/CD pipelines, and pair programming sessions all leverage the exact same IaC tooling surface, ensuring state file integrity and predictable provider behaviors.
- Version-pinned per directoryUses .terraform-version, .tfenvrc, or environment variable.
- Signature-verified downloadsChecks SHA256 checksums when the required tool is available; signature checks can be configured.
- Shell-agnosticBash and Zsh workflows, plus documented Windows Git Bash support.
- Offline cacheAlready-downloaded versions never hit the network again.
live_demo.tfenv
Cross-Platform Tfenv Installation Guide
Three official channels. Pick the one that matches your DevOps workflow — package manager for macOS, direct download for Linux servers, and a quick script for Windows. Or just download the archive directly.
Download Tfenv .zip ArchivemacOS Terraform Version Manager Setup
Install using Homebrew and keep tfenv updated with your normal package workflow.
brew tap tfutils/tfenv
# Install
brew install tfenv
Linux / POSIX Shell Setup
Clone the upstream repository, add tfenv to PATH and use it from your shell.
# Add to your shell config:
export PATH="$HOME/.tfenv/bin:$PATH"
Windows: Git Bash or WSL
The upstream project documents 64-bit Windows through Git Bash with Git symlinks enabled. WSL provides a Linux-style alternative.
git config --global core.symlinks true
# Or use a WSL Linux environment
# Follow the Linux setup there
Everything your Terraform workflow needs.
Nothing it doesn't.
A focused toolkit for version consistency, secure downloads and reliable delivery — from your laptop to the pipeline.
Secure Terraform downloads, without the guesswork.
Verify binaries against HashiCorp's published SHA256 checksums when the required checksum tool is available. Optional signature-verification workflows add another layer of assurance.
Switch versions without slowing down.
Move between projects with different Terraform requirements. Tfenv resolves the selected version and uses locally installed releases when available.
Project-aware selectionInternal mirrors and restricted networks.
Use TFENV_REMOTE to source Terraform releases from a configured internal endpoint, where your network and artifact policies permit.
One version across the entire team.
Commit .terraform-version with your repository so new teammates and automation know which CLI release to use.
Less repetition in CI/CD.
Cache downloaded Terraform versions between CI jobs to reduce repeated downloads and keep builds more predictable.
Reusable local versionsLightweight by design.
Shell-based tooling that fits into existing development setups without requiring a heavy application or a background service.
Minimal footprintDifferent repos, different releases.
Keep independent version files inside services or repository directories, so each workload can use the CLI version it needs.
Flexible team structureChoose exact or matching releases.
Install a specific release, the latest available, or a matching series with tfenv's supported version selection syntax.
tfenv install latest:^1.9 The Standard Tfenv DevOps Workflow
Most users run exactly four commands per project, ever. The rest of the time, Tfenv is silent, ensuring smooth Infrastructure as Code operations.
Pin Terraform Version
Establish strict version control by committing a .terraform-version file to your IaC repository.
echo "1.9.5" > .terraform-version
Install Terraform CLI On Demand
Run tfenv install with no arguments. It reads the pin and downloads the correct HashiCorp binary.
tfenv install
Execute Infrastructure as Code
The terraform command on your PATH now points at the pinned release.
terraform plan
Switch Terraform Projects Instantly
Cd into another repo. Tfenv re-reads the pin and swaps the shim instantly without manual uninstall.
cd ../billing-api
Essential Tfenv Commands & CLI Reference
The CLI surface is intentionally small. Eight verbs cover installing, listing, switching, and uninstalling Terraform versions. Below is the full reference for DevOps automation and IaC version management.
HashiCorp Terraform Release Catalog
Explore examples of Terraform releases you can select with tfenv. For the actual up-to-date list on your machine, run tfenv list-remote.
Real-World Use Cases for Tfenv
From local laptops to air-gapped production floors — same tool, same flags, same outcomes. Tfenv adapts to any DevOps or Infrastructure as Code environment.
Day-One Terraform Developer Onboarding
New engineer clones your repo, runs make bootstrap, and Tfenv installs the exact Terraform the team uses. No wiki hunting, no Slack thread archaeology, just immediate IaC productivity.
- Reads
.terraform-versionon cd - Skips re-download if cached
- Surfaces upgrade warnings
Reproducible Terraform CI/CD Pipelines
Cache ~/.tfenv between jobs and your terraform plan step drops from 90 seconds to under 5. Pin once, run thousands of times with perfect IaC state consistency.
- Cache key per
.terraform-version - Works with automated CI runners
- Headless — no interactive prompts
Air-Gapped Terraform Mirror Mode
Point TFENV_REMOTE at your artifact server. Tfenv downloads from there and verifies against your internal GPG key. No public internet required for secure Infrastructure as Code deployments.
- Set
TFENV_REMOTEenv var - Custom
TFENV_GPG_KEYRING - Logging friendly to audit teams
Per-Tenant Terraform Version Pinning
Platform teams running Terraform for multiple customers can pin different versions per tenant directory. Switching contexts becomes a cd, not a reinstall, streamlining multi-tenant IaC operations.
- Isolated
TFENV_DATA_DIRper tenant - Concurrent terraform processes
- Audit log of every switch
Tfenv in Action: Terminal Walkthrough
This is the exact sequence you'd run joining a new infrastructure repo. Four commands, three seconds, zero ambiguity. A perfect demonstration of seamless Terraform CLI version management.
One workflow. Every environment.
Manage Terraform releases across supported workstations and pipelines, with platform-specific guidance and room for every team setup.
From your laptop to your infrastructure fleet.
Tfenv is shell-based; the Terraform binary it downloads is selected for your platform and architecture. Keep versions consistent without maintaining a different process for every machine.
macOS
Develop on Intel or Apple Silicon. Install tfenv with Homebrew, then manage project-specific Terraform versions directly from your shell.
Linux
Keep Terraform releases aligned across developer machines, hosted runners and Linux servers with standard shell tooling.
Windows workflows
The upstream project documents Windows 64-bit use through Git Bash, with symlinks enabled. WSL is another practical Linux-based option.
Containers & CI
Install the matching Terraform release in build jobs and container images that include the shell and utilities tfenv requires.
CPU architectures
Manage supported Terraform builds on common 64-bit and ARM machines. The available Terraform release determines the exact target binaries.
Shell environments
Use tfenv in documented POSIX-style environments such as Bash or Zsh. For Windows, follow the tested Git Bash setup.
A cleaner path from setup to ship.
Small, repeatable steps make it easier to keep your Terraform CLI selection consistent across projects and teams.
Choose the exact version that your project requires.
Track .terraform-version alongside your code.
Resolve the release and download it when needed.
Use the selected Terraform CLI in your workflow.
Tfenv vs Other Version Managers
Not every tool optimizes for the same thing. Here's an honest comparison so you can pick what fits your Infrastructure as Code stack.
Frequently Asked Questions about Tfenv
Explore 25 of the most searched questions about the Tfenv Terraform version manager, categorized by DevOps workflow. Tap any card to expand. Still stuck? The community is fast.
Need human help?
Open a discussion on the Tfenv community portal or join our DevOps chat — see community discussions and official documentation for guidance.
Browse GuidesYou can install the Tfenv version manager by downloading the official archive and extracting it into your ~/.tfenv directory, then adding the bin folder to your system PATH. Alternatively, macOS users can install it via Homebrew using brew install tfenv.
On Windows, you can extract the Tfenv version manager into your %USERPROFILE%\.tfenv directory using PowerShell. You must then manually add the .tfenv/bin directory to your Windows PATH environment variables to use the tfenv command for Infrastructure as Code automation.
No, Tfenv is designed to be completely dependency-free. It is built as a POSIX-compliant shell script. As long as your system has a standard shell environment (like Bash or Zsh) and curl or wget for downloading HashiCorp binaries, Tfenv will run perfectly.
You can download the latest master branch directly as a zip archive from the official source. Extract it and place the contents in your target installation directory to start managing your Infrastructure as Code versions.
Yes, Tfenv has an official Homebrew formula. You can install it on macOS by running brew install tfenv. This is the fastest and most maintainable installation method for Mac users managing Terraform CLI versions.
To pin a version, navigate to your Infrastructure as Code project root and run tfenv pin <version>. Alternatively, manually create a .terraform-version file containing the exact version number. Tfenv will automatically use this version whenever you enter the directory.
Yes. Tfenv supports monorepos by walking up the directory tree. You can place .terraform-version files in different subdirectories. When you cd into a specific service's folder, Tfenv reads the nearest pin file and switches versions instantly.
The .terraform-version file is a simple text file containing the exact Terraform CLI version your project requires. Tfenv reads this file automatically to download, install, and shim the correct binary without manual intervention.
You can switch versions by running tfenv use <version>. If the version is already installed locally, Tfenv will switch to it immediately. If it is not installed, Tfenv will prompt you to run tfenv install first.
Yes, Tfenv can install pre-release versions like alphas, betas, and release candidates. Simply run tfenv install latest:^1.10 or specify the exact pre-release string like tfenv install 1.10.0-rc1.
To use Tfenv in CI/CD pipelines, add a step to install Tfenv via download, then run tfenv install. To speed up pipelines, cache the ~/.tfenv directory using your CI provider's caching mechanism so binaries are downloaded only once.
Yes, in GitLab CI, you can use the cache keyword with a key pointing to your .terraform-version file. Configure the cache paths to include the ~/.tfenv/versions directory to prevent re-downloading the HashiCorp binaries on every pipeline run.
Always commit the .terraform-version file to your repository. This ensures that both local developers and CI/CD runners use the exact same Terraform CLI version, preventing state file corruption and unpredictable provider behaviors.
Yes, Tfenv is lightweight and works perfectly in Docker containers, including Alpine Linux. You just need to install standard shell utilities (bash, curl, tar) in your Dockerfile before running the Tfenv installation script.
You can set TFENV_TERRAFORM_VERSION to bypass reading the .terraform-version file, and TFENV_AUTO_INSTALL=true to allow Tfenv to automatically download the required version without interactive prompts, which is ideal for CI runners.
Tfenv automatically downloads the SHA256SUMS file published by HashiCorp alongside the Terraform release. It verifies the checksum of the downloaded zip file against this list to ensure the binary has not been corrupted during download.
Yes. You can point the TFENV_REMOTE environment variable to an internal HTTP server or artifact repository (like Artifactory or Nexus) hosting the Terraform binaries and checksums.
Export the TFENV_REMOTE environment variable with the base URL of your internal mirror (e.g., export TFENV_REMOTE='https://internal-mirror.corp.com/tf'). Tfenv will append the specific version paths to this base URL.
By default, Tfenv performs SHA256 verification. For strict enterprise GPG signature verification, you can provide your own HashiCorp GPG public key by configuring the TFENV_GPG_KEYRING environment variable.
Yes. Tfenv does not phone home, collect telemetry, or require external runtimes. It simply wraps HashiCorp's official binaries in a localized user directory, making it compliant with strict enterprise security policies.
This usually happens if your shell PATH is pointing to a system-installed Terraform rather than Tfenv's shim. Ensure ~/.tfenv/bin is prepended to your PATH at the very beginning of your shell configuration file.
To uninstall a version, run tfenv uninstall <version>. Tfenv will refuse to uninstall the currently active version unless you pass the --force flag, which prevents accidental removal during an active deployment.
If you are behind a corporate proxy, set the standard HTTPS_PROXY and HTTP_PROXY environment variables. If the proxy uses a custom CA certificate, point TFENV_CURL_OPTIONS to the certificate bundle.
If you installed via direct download, simply download the latest archive and replace the existing files. If you used Homebrew, run brew upgrade tfenv. This ensures you have the latest features and support for new Terraform releases.
By default, the Tfenv script is stored in ~/.tfenv. The downloaded Terraform binaries are stored in ~/.tfenv/versions/<version>, and the active shim is symlinked in ~/.tfenv/bin. You can change this using the TFENV_ROOT variable.
Advantages and Limitations of Tfenv
We love Tfenv, but no tool is perfect for every scenario. Here's an honest look at where it shines and where it might fall short for Infrastructure as Code teams.
Tfenv Advantages for DevOps Teams
-
Zero DependenciesNo Node.js or Python runtime required; standard shell and download utilities are used.
-
Project-Level PinningPrevents version drift effortlessly across team members and CI runners.
-
Security FirstSHA256 verification is supported; signature verification requires a supported setup.
-
Air-Gapped SupportWorks in restricted environments via internal mirrors without public internet access.
-
Blazing FastInstalls cached versions in milliseconds, saving precious CI pipeline minutes.
Tfenv Limitations & Considerations
-
Terraform OnlyUnlike polyglot version managers, Tfenv doesn't manage other tools like Node or AWS CLI.
-
Shell-Script BasedSlightly slower execution than compiled Go binaries, though unnoticeable in practice.
-
No GUIStrictly CLI-driven, which might deter beginners who prefer graphical interfaces.
-
Windows SetupRequires manual PATH configuration on native Windows, though WSL2 works perfectly.
-
Learning CurveRequires basic shell scripting knowledge to troubleshoot edge cases effectively.
Good tooling disappears into the workflow.
Three common ways development and platform teams can use project-level Terraform version management.
Onboard without version guesswork.
A new team member checks out an IaC repository, reads its .terraform-version file and installs the expected Terraform CLI with tfenv.
Support repositories at different versions.
Different services can maintain their own pins. Developers can move between codebases without repeatedly replacing one system-wide Terraform installation.
Keep deployment jobs predictable.
Automated jobs can install the pinned Terraform version. Caching previously downloaded binaries may help reduce repeated work across pipeline runs.