Terraform Version Management#

Atlantis resolves and downloads Terraform (and OpenTofu) binaries on demand. At its core, the system answers: "given a requested version, return a path to a valid binary — downloading it if necessary." The key types are in server/core/terraform/.

Version Selection#

Atlantis determines which binary version to use in precedence order:

1. terraform_version in atlantis.yaml — highest priority 1
2. required_version in Terraform/OpenTofu HCL — exact pin (= x.y.z) or version constraint (~> 1.2, >= 1.2.0) 2
3. --default-tf-version server flag — fallback if neither of the above resolves 3
4. Terraform binary in $PATH — used as default if --default-tf-version is unset 4

Version constraints in HCL are resolved against the live release index. Atlantis selects the highest version satisfying the constraint 5. When downloads are disabled, only exact version pins (= x.y.z or bare x.y.z) are accepted — range constraints are skipped 6.

Download Architecture#

The download path runs through two layers:

Distribution interface (server/core/terraform/distribution.go) — abstracts the two supported distributions:

• DistributionTerraform — wraps hc-install + HashiCorp's release API 7
• DistributionOpenTofu — wraps tofudl 8

Downloader interface (server/core/terraform/downloader.go) — called by the distribution to perform the actual install:

• TerraformDownloader uses hc-install's releases.ExactVersion, passing ApiBaseURL = the configured download URL. After install, the binary is renamed from terraform → terraform{version} to match Atlantis's naming convention.
• TofuDownloader uses tofudl.Download() and writes tofu{version} to disk.

The orchestration lives in ensureVersion (terraform_client.go). The lookup order before triggering a download:

1. In-memory versions map
2. Binary named {binName}{version} found in $PATH
3. Binary found in binDir on disk (survives Atlantis restarts) 9

If the binary is found but fails execution validation (terraform version returns an error), Atlantis automatically re-downloads a fresh copy (introduced in PR #6454). Only binaries managed within binDir are deleted; binaries found in $PATH are left untouched 10.

Key Server Flags#

The --tf-download-url flag is passed as ApiBaseURL directly to hc-install's ExactVersion installer 15, so any HTTP server serving the standard HashiCorp release artifact layout can act as a mirror.

Note: Constraint resolution via ResolveConstraint always hits the public HashiCorp or OpenTofu registry API regardless of --tf-download-url. Custom mirrors only affect binary artifact downloads, not version listing.

Air-Gapped Environments#

Set --tf-download=false to prevent any outbound download attempts 13. In this mode:

• Only exact version pins in required_version are honored 6.
• Binaries must be pre-staged either in $PATH (named terraform{version} / tofu{version}) or in binDir.
• The error when a version is missing: "could not find {bin} version {v} in PATH or {binDir}, and downloads are disabled" 16.

For container deployments, Atlantis publishes -slim image variants (e.g. alpine-slim, debian-slim) that ship without any pre-bundled Terraform or OpenTofu binaries (PR #6831). Operators can mount or copy binaries in and set --tf-download=false.

OpenTofu Distribution#

Switch the server default with --default-tf-distribution=opentofu. Projects can also override per-project in atlantis.yaml via terraform_distribution: opentofu 17.

When the effective distribution is OpenTofu, Atlantis reads required_version from .tofu and .tofu.json files in addition to .tf / .tf.json, with .tofu taking precedence over a same-basename .tf 18. The terraform-config-inspect library (used for Terraform distribution) does not read .tofu files 19.

Known limitation: --autoplan-modules dependency indexing does not yet fully support .tofu / .tofu.json files for module source blocks 20.

Primary Source Files#