Who Wins the Variable Fight in Terraform?

A beginner friendly guide to understanding which value Terraform actually picks when the same variable is set in many places

Introduction

When you start writing Terraform, you quickly learn that you can set the same variable in many different ways. You can give it a default value, you can put it in a file, you can pass it on the command line, and you can even set it through your computer's environment.

This is great for flexibility, but it also raises a confusing question. If the same variable gets a value from five different places, which value does Terraform actually use?

This is called variable precedence. Precedence simply means the order of priority. It is the set of rules Terraform follows to decide who wins when there is a conflict.

In this post we will walk through every way you can set a variable, then look at the exact order Terraform uses to pick a winner. We will use small, repeatable examples so you can try each one yourself.

Quick note on the words we will use. A variable is just a named value you can reuse, like a name tag on a box. A value is what is inside that box. Precedence is the priority order Terraform uses when two boxes have the same name tag but different contents.

First, the ways you can set a variable

Before we talk about who wins, let us list all the players in the game. There are six common ways to give a variable a value in Terraform.

The first is a default value. You write this directly inside the variable block in your code.

variable "region" {
  type    = string
  default = "us-east-1"
}

The second is an environment variable. An environment variable is a value stored in your computer's shell, outside of Terraform. Terraform reads any environment variable that starts with TF_VAR_ followed by the variable name.

export TF_VAR_region="us-west-2"

The third is a file called terraform.tfvars. A tfvars file is a plain file where you list variable names and the values you want to give them. Terraform loads this file automatically without you doing anything.

region = "ap-south-1"

The fourth is a file called terraform.tfvars.json. This is the same idea as above, but written in JSON format instead. JSON is just another way of writing structured data using curly braces and quotes.

{
  "region": "eu-west-1"
}

The fifth is any file ending in .auto.tfvars or .auto.tfvars.json. The word auto here means automatic. Terraform loads these files for you automatically too, just like the standard tfvars file. A common example name is prod.auto.tfvars.

region = "ca-central-1"

The sixth is a command line flag. A flag is an extra instruction you type when running a command. You can pass a value directly with -var, or point to a specific file with -var-file.

terraform apply -var="region=sa-east-1"

The order that decides the winner

Here is the part everyone wants to know. Terraform checks these sources in a fixed order, from lowest priority to highest priority. A source that comes later in the list overrides anything set earlier.

Here is the order from weakest to strongest.

The default value inside the variable block. This is the fallback that is used only when nothing else provides a value.
Environment variables that start with TF_VAR_.
The terraform.tfvars file.
The terraform.tfvars.json file.
Any files ending in .auto.tfvars or .auto.tfvars.json, loaded in alphabetical order of their file names.
The -var and -var-file flags on the command line, applied in the exact order you type them. The simplest way to remember this is that the command line always wins, and the default value always loses. Everything else sits in the middle.

A full example you can run

Let us prove the rules with a tiny project. Create a folder and add the following files.

First the variable declaration in a file called variables.tf.

variable "region" {
  type    = string
  default = "us-east-1"
}

Next a file called main.tf that just prints the value back to us using an output. An output is simply a way for Terraform to show you a value after it runs.

output "selected_region" {
  value = var.region
}

Now run this command to see the result.

terraform apply

At this point only the default exists, so Terraform will show us-east-1. The default wins because nobody else is competing.

Now add a file called terraform.tfvars with this line.

region = "ap-south-1"

Run apply again. This time Terraform shows ap-south-1. The tfvars file beat the default because it has higher priority.

Now add a file called prod.auto.tfvars with this line.

region = "ca-central-1"

Run apply once more. Now the answer becomes ca-central-1. The auto tfvars file sits higher than the standard tfvars file, so it takes over.

Finally, run apply with a command line flag.

terraform apply -var="region=sa-east-1"

The result is now sa-east-1. The command line beats every file, so it has the final say.

What happens with two auto tfvars files

A common question is what happens when you have more than one auto tfvars file and both set the same variable. The answer is alphabetical order.

Imagine you have two files named a.auto.tfvars and b.auto.tfvars, and both set the region. Terraform loads a.auto.tfvars first and b.auto.tfvars second. Because the later one overrides the earlier one, the value inside b.auto.tfvars wins.

So the file whose name comes later in the alphabet has the higher priority. This is easy to forget, so name your files carefully if order matters to you.

Command line order also matters

There is one more detail worth knowing. When you pass several flags on the command line, Terraform applies them left to right, and the rightmost one wins.

terraform apply -var="region=us-east-1" -var="region=us-west-2"

In this case the final value is us-west-2, because it appears last. The same rule applies when you mix -var and -var-file. Whatever comes last on the line takes priority.

A quick warning about missing values

If a variable has no default and you never give it a value through any source, Terraform will stop and ask you to type the value in. This is a safety feature so you never accidentally run with a blank value.

If you want a variable to be optional, give it a sensible default. If you want it to be required on purpose, leave the default out so Terraform forces someone to provide it.

Conclusion

Variable precedence in Terraform looks confusing at first, but it follows one calm and predictable rule. Lower priority sources set the value, and higher priority sources override it.

The order, from weakest to strongest, is the default value, then environment variables, then the standard tfvars file, then the JSON tfvars file, then the auto tfvars files in alphabetical order, and finally the command line flags which always win.

Once this clicks, you gain real control over your setup. You can keep safe defaults in your code, store normal settings in tfvars files, and override anything on the fly from the command line when you need to. That is the whole point of precedence, giving you layers you can trust.

Try the small example above and watch the value change with each step. Seeing it happen is the fastest way to make this stick.