What Is Terraform State? Explained Simply

Run terraform apply and a file called terraform.tfstate appears. Every guide warns you never to hand-edit it, but few explain what it actually is. State is the one genuinely new idea in Terraform — get it, and the whole tool stops feeling like magic.

The problem state solves

Your .tf files describe what you want to exist. But when you run apply a second time, how does Terraform know the server it made last time already exists, so it doesn't build a duplicate? It has to remember what it created. That memory is state.

What state actually is

terraform.tfstate is a JSON file that records, for every resource in your config, the real object Terraform created for it — its ID, its attributes, and the link back to the resource block in your code. It's the map between your configuration and reality:

• Your config says resource "aws_instance" "web".
• State records that web = real instance i-0abc123 with these attributes.

When you run plan, Terraform compares three things: your config (desired), state (what it last built), and the real world (what's actually there), and works out the smallest set of changes to reconcile them.

Why you never hand-edit it

Because state is that map, editing it by hand desyncs Terraform from reality — it can lose track of real resources, or try to recreate things that already exist. If you need to change what's tracked, use the terraform state commands (state mv, state rm) rather than a text editor.

Why teams move it off the laptop

A local terraform.tfstate is fine for one person. For a team it's a problem: it isn't shared, isn't locked, and can hold secrets in plain text. Teams put state in a remote backend (S3 + DynamoDB, pg, Terraform Cloud) so everyone shares one source of truth, with locking so two applies can't collide.

The mental model to keep

State is Terraform's notebook of "what I built and where it is." Your .tf files are the plan; state is the record of what the plan produced. Terraform reads both on every run to figure out the difference — which is why state exists, why you protect it, and why you never edit it by hand.

Frequently Asked Questions

What is the terraform.tfstate file? It's Terraform's record of the real infrastructure it created — a JSON map linking each resource in your configuration to the actual object (ID and attributes) that exists. Terraform reads it to know what already exists before planning changes.

Why can't I edit terraform.tfstate by hand? Because it's the map between your code and real resources; editing it desyncs Terraform from reality and can make it lose track of or duplicate resources. Use terraform state mv / terraform state rm to change what's tracked instead.

Where should Terraform state be stored for a team? In a remote backend such as S3 with DynamoDB locking, the pg backend, or Terraform Cloud — so the whole team shares one locked source of truth instead of separate local files that can conflict.