Terraform Environment Variables – How to Use Them

An Introduction to Terraform Environment Variables

In this article, we will look at what Terraform environment variables are, when and why you would use them, and how to set them with examples of each! Let’s jump straight in!

We will cover:

  1. What is a Terraform environment variable?
  2. How to use different Terraform Environment Variables

What is a Terraform Environment Variable?

Terraform refers to a number of environment variables to customize various aspects of its behavior. These variables are set within the environment in which Terraform is running. They provide configuration information to Terraform without having to hardcode it into the configuration files.

Environment variables can be set on the command line, within scripts, or by using the operating system’s environment variable settings.

For reference, using the GUI in a Windows OS, they can be set Under System Properties → Advanced → Environment Variables → New system variable.

On the command line in a Windows system, you can use the SET command as an equivalent to the export on Linux based system, and view the current value using %<variable name>%:

set TF_LOG=trace

In Spacelift, environment variables can be defined directly on stacks and modules, as well as on contexts attached to those. Read more about using environment variables in our documentation.

The following examples in this article use the export command which is native to Linux of MacOS (but is not available on a Windows OS).

How to Use Different Terraform Environment Variables

1) TF_VAR_name

As well as defining variables using a .tfvars files and directly on the command line, this environment variable can be used to values for variables in your Terraform configuration.

Note that defining variables this way is a fallback if variable values are not found elsewhere.

The variable name you want to set the value for should be in the format _name, e.g., for a variable named region, you would specify TF_VAR_region as the variable name. This can be useful when running Terraform in automation, or when running a sequence of Terraform commands in succession with the same variables.

export TF_VAR_region=uksouth
export TF_VAR_regionlist='[uksouth,ukwest,useast2]'
export TF_VAR_tagmap='{ Environment = "dev", Project = "demo" }'


For debugging purposes, this variable enables detailed logs in stderr.

export TF_LOG=trace

You can set TF_LOG to one of the log levels (in order of decreasing verbosity) TRACEDEBUGINFOWARN or ERROR to change the verbosity of the logs.

Setting TF_LOG to JSON outputs logs at the TRACE level or higher, and uses a parseable JSON encoding as the formatting.

You can turn off logging when you have finished debugging:

export TF_LOG=off


When TF_LOG is set, you can also use the TF_LOG_PATH variable to set the location where the log should persist its output to. The below example logs to a file called terraform.log in the local directory.

export TF_LOG_PATH=./terraform.log


This is useful when you want to replicate the -input=false flag behavior from the command line in an environment variable by specifying a value of 0 or FALSE. This disables prompts for input for variables that have not been specified.

export TF_INPUT=0


TF_CLI_ARGS is used to specify additional arguments to the command line. Arguments are inserted directly after the subcommand (such as plan) and before any flags specified directly on the command line. This behavior ensures that flags on the command line take precedence over environment variables.

For example, to run Terraform plan with the debug mode enabled and specify the location of the state file, you can set the TF_CLI_ARGS variable to -state=terraform.tfstate -debug, which will pass the -state and -debug options to Terraform CLI.

export TF_CLI_ARGS="-state=terraform.tfstate -debug"

When the terraform plan command is run, Terraform will use the state file specified and output additional debugging information to the console.

A named command can also be specified, which will only affect that command. This is done using the TF_CLI_ARGS_name variable.

For example, to specify that only plans never refresh:

export TF_CLI_ARGS_plan="-refresh=false"


By default, Terraform working data is written into a .terraform subdirectory of the current directory. To change the path that this data is held in, the TF_DATA_DIR can be used (useful in rare cases where the working directory is not writeable).

In automation, this must be set at each stage of the Terraform workflow for each command, e.g. terraform init , terraform plan , terraform apply — as each command will need to reference the working directory if it is changed from the default to find modules and configuration information.

export TF_DATA_DIR=./mydirectory/terraform


This is the environment variable equivalent of setting your workspace using:

terraform workspace select my_workspace_name

This is useful in automation as it overrides any workspace selection but is not recommended when using Terraform interactively as it is easy to set and forget, which might cause inadvertent changes to the wrong Terraform state.

For example:

export TF_WORKSPACE=my_workspace_name


This is a variable used to set a purely cosmetic change to Terraform’s human-readable output, which prevents it from suggesting specific commands to run next after one command has been completed.

In automation, this wouldn’t be possible as the environment is non-interactive, so removing these suggestions makes the output less confusing. To use it, set it to any non-empty value.

export TF_IN_AUTOMATION=true


Used to specify the location of the Terraform CLI configuration file. This is a file specified as .terraformrc or terraform.rc which configures per-user settings for CLI behaviors, which apply across all Terraform working directories.

export TF_CLI_CONFIG_FILE=”./mydirectory/.terraformrc-custom”


When debugging large repositories with .terraformignore files, this variable can be used to get Terraform to output debug messages to display ignored files and folders. It should be set to trace .

Files listed in a .terraformignore plan are simply a list of files that should not be considered as part of the configuration to speed up deployments when a large number of file exist.

export TF_IGNORE=trace


Set TF_REGISTRY_DISCOVERY_RETRY to configure the max number of request retries, the remote registry client will attempt for client connection errors or 500-range responses that are safe to retry.


This example sets the value of TF_REGISTRY_DISCOVERY_RETRY to ten, which means that registry discovery operations will be retried up to ten times before failing.


This variable can be configured to increase the default client timeout to the remote registry during extraneous circumstances.

The default client timeout for requests to the remote registry is 10s.


Key Points

Terraform environment variables provide a flexible and secure way to manage configuration information, making it easier to use Terraform in a variety of environments and scenarios.

No environment variables are required when using Terraform, but they can be helpful to change some of Terraform’s default behaviors in unusual situations.

We encourage you also to explore how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this.

Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6. OpenTofu retained all the features and functionalities that had made Terraform popular among developers while also introducing improvements and enhancements. OpenTofu works with your existing Terraform state file, so you won’t have any issues when you are migrating to it.

Terraform Management Made Easy

Spacelift effectively manages Terraform state, more complex workflows, supports policy as code, programmatic configuration, context sharing, drift detection, resource visualization and includes many more features.

Start free trial
Terraform CLI Commands Cheatsheet

Initialize/ plan/ apply your IaC, manage modules, state, and more.

Share your data and download the cheatsheet