Terraform State File Explained: Local State, Remote State, Locking, and Best Practices

Terraform State File Explained#

Understand what Terraform state is, why it matters, how local and remote state work, why locking is important, and how to avoid dangerous state mistakes.

What is Terraform state?#

Terraform state is how Terraform remembers the infrastructure it manages. The state maps Terraform resources in your code to real resources in the cloud or platform.

Why state matters#

• Terraform uses state to compare desired configuration with real infrastructure.
• State helps Terraform know what to create, update, or destroy.
• State can contain sensitive information, depending on resources and providers.

Local state#

By default, Terraform stores state in a local file named terraform.tfstate .

terraform.tfstate terraform.tfstate.backup

Remote state#

For team projects, use a remote backend so state is shared, protected, and locked.

State locking#

Locking prevents two users or pipelines from changing the same state at the same time.

Common commands#

terraform state list terraform state show RESOURCE terraform refresh terraform plan

Common mistakes#

• Committing terraform.tfstate into Git.
• Manually editing state without understanding the impact.
• Running Terraform from multiple machines against local state.
• Ignoring state locking in team projects.
• Destroying resources from the wrong workspace or backend.

Related guides#

• Terraform Learning Path
• Terraform Remote Backend Guide