What Is a Terraform State File (tfstate)?

Before you read on

This is the short definitional answer to “what is the Terraform state file?” — about a five-minute read. If you want the full operational guide on remote state, locking, backends and team workflows, jump to Manage Terraform state. If you want everything else Terraform-related, the Terraform category has the wider catalogue.

Prerequisites

• Terraform 1.0 or later installed (1.5+ in 2026).
• Awareness that this post is the short definitional answer; for the full operational guide, see the linked deeper article.

This page answers one narrow question: what is the Terraform state file, often called tfstate? If you need the complete guide to remote state, locking, backends, and operational best practices, read Terraform State Explained: Remote State, Locking, Backends, and Best Practices.

What is a Terraform state file?

A Terraform state file is the record Terraform keeps to map your configuration to the real resources it manages. By default, Terraform writes that record to a file commonly named terraform.tfstate.

Terraform uses the state file to answer practical questions such as:

• Which real resource belongs to this resource block?
• What attributes did the provider return last time?
• What has changed since the previous plan or application?

What does tfstate normally contain?

The file usually contains resource addresses, IDs, attributes returned by providers, outputs, dependency information, and some Terraform bookkeeping metadata.

That is why teams treat the state file as operational data rather than a casual artifact. It may include values you would not want exposed broadly.

Why does Terraform need it?

Without a state, Terraform would struggle to work out what it had already created. State lets Terraform compare your code to reality and build an accurate execution plan.

That helps Terraform decide whether to create, update, replace, import, or destroy resources.

Should you edit tfstate manually?

Usually, no. Manual edits are risky because they can break the mapping between your code and your infrastructure. In normal workflows, use Terraform commands instead:

terraform state list
terraform state show
terraform state mv
terraform state rm

terraform state list
terraform state show
terraform state mv
terraform state rm

Back up state before any advanced refactor and avoid hand edits unless you are dealing with a controlled recovery scenario.

When should you move on from local tfstate?

Local state is acceptable for labs and personal experiments. As soon as a project becomes shared, important, or automated through CI, move to a remote backend and follow a documented workflow.

• Use the main Terraform state guide for the bigger operational picture.
• Use the AWS account migration guide if you need to move remote state between accounts.

This page stays intentionally short so it can rank for the tfstate definition query without duplicating your broader Terraform state content.

Verification — inspecting your state file

Useful commands for poking at state without changing it:

• terraform state list — prints every resource in the current state file. Sanity-checks both that you have a state file and that it tracks what you expect.
• terraform state show <address> — dumps the full attributes Terraform thinks a specific resource has.
• terraform refresh (or terraform plan -refresh-only) — re-syncs state with reality and shows any drift.

Troubleshooting — common state-file situations

Error: state file already locked — Another Terraform run is in flight, or a previous run crashed without releasing the lock. Wait, then terraform force-unlock <lock-id> if you’re certain nothing else is running. The lock-id is in the error message.

State file out-of-sync with reality (drift) — Someone changed a resource manually in the cloud console. Run terraform plan -refresh-only to see the drift, then either bring the change into your config or use lifecycle.ignore_changes to permanently exclude it from Terraform’s view.

Resource needs to be moved to a different module — Use terraform state mv aws_instance.old module.app.aws_instance.new. Never edit the state file by hand — the move command updates checksums and bookkeeping correctly.

Want to remove a resource from state without destroying it — terraform state rm <address>. The resource stays in the cloud; Terraform simply forgets it. Often paired with terraform import to bring it under different management.

Accidentally committed terraform.tfstate to git — Stop. The file may contain secrets. Rotate any sensitive credentials, then rewrite git history (git filter-repo) and force-push if the repo is private. Add *.tfstate* to .gitignore immediately.

Authoritative sources

References: Terraform — State documentation, terraform state command reference, Backends — for remote state.

Related reading

• Manage Terraform state — the full operational guide on remote state, locking and backends
• Important Terraform concepts
• How to structure your Terraform code
• Reading and saving Terraform plan output
• Migrate from template_file data sources
• OpenTofu vs Terraform (2026)
• AWS Start Here