Terraform State File What It Is and Why It Matters

The state file is Terraform's memory. Without it, Terraform cannot know what infrastructure already exists, what needs to change, and what should be left alone. Understanding the state file is essential to avoiding dangerous mistakes in real projects.

What Is the State File

Every time you run terraform apply, Terraform saves a record of every resource it created. This record is stored in a file called terraform.tfstate. The file is written in JSON format and lives in your working directory by default.

Analogy: The Inventory Ledger

Think of the state file like a warehouse inventory ledger. The warehouse manager (Terraform) writes down every item on the shelf (resource) with its exact details — ID, location, size, properties. Next time the manager checks, they compare the ledger to the actual shelves. If something changed, they know exactly what to add, modify, or remove to bring the warehouse back to what the ledger says it should look like.

What the State File Contains

Open a terraform.tfstate file and you will find structured JSON with sections like this:

{
  "version": 4,
  "terraform_version": "1.9.0",
  "resources": [
    {
      "type": "aws_instance",
      "name": "web_server",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "attributes": {
            "id": "i-0abc123def456",
            "ami": "ami-0c55b159cbfafe1f0",
            "instance_type": "t3.micro",
            "public_ip": "54.210.123.45",
            ...
          }
        }
      ]
    }
  ]
}

Every resource has its type, name, and all of its attributes — including values assigned by the cloud provider like instance IDs and IP addresses that you did not specify in your code.

How Terraform Uses the State

Diagram: The Three-Way Comparison

  Your .tf files          State file           Real cloud
  (desired state)      (recorded state)       (actual state)
        |                    |                      |
        +--------------------+----------------------+
                             |
                      Terraform compares all three
                             |
                             v
                  Calculates what actions to take:
                  - Create: in .tf, not in state
                  - Update: .tf differs from state
                  - Delete: in state, not in .tf
                  - No change: .tf matches state

Without the state file, Terraform cannot perform this comparison. It would try to create everything from scratch every time — causing duplicate resources and errors.

State File Location and the .terraform.tfstate.backup File

By default, Terraform writes state to terraform.tfstate in your working directory. Before every apply, it also saves the previous state to terraform.tfstate.backup. If something goes wrong with the latest apply, the backup gives you a recovery point.

Why You Must Not Edit the State File Manually

The state file is not a configuration file you are supposed to edit by hand. Manual edits corrupt the JSON structure or create attribute mismatches that Terraform cannot reconcile. Corrupted state can lead to Terraform trying to delete resources that still exist or create duplicates of resources already running.

When you need to manipulate state, use the official Terraform commands designed for it:

The .gitignore Rule for State Files

The state file often contains sensitive data — database passwords, private IPs, access keys that providers store in resource attributes. You should never commit terraform.tfstate to a Git repository.

Add this to your .gitignore file:

# Terraform state files
terraform.tfstate
terraform.tfstate.backup

# Terraform plugin cache
.terraform/

For teams, the correct solution is remote state storage — storing the state file in a shared, secure location like S3 or Azure Blob Storage. This is covered in a later topic.

State Drift

State drift happens when someone makes a change to real infrastructure outside of Terraform — directly in the cloud console, via the CLI, or through another tool. Now the real infrastructure differs from what the state file records. Terraform does not know about this change until the next plan.

Run terraform plan regularly to detect drift. Terraform compares its state to the real cloud and flags any differences.

You can also force Terraform to re-read the real state of all resources:

terraform apply -refresh-only

This updates the state file to match actual cloud reality — without making any changes to resources.

Key Points

• The state file (terraform.tfstate) is Terraform's record of everything it has created.
• Terraform compares your code, the state file, and the real cloud to decide what actions to take.
• Never edit the state file manually — use terraform state subcommands instead.
• Never commit terraform.tfstate to version control — it may contain sensitive data.
• State drift occurs when changes happen outside Terraform; use terraform apply -refresh-only to reconcile.