How to Move Terraform State Safely

State is where Terraform keeps its map between your configuration and the real resources it manages. Rename a resource in code without telling Terraform, and it reads the change as "destroy the old thing, create a new one." For a security group that might be harmless. For an RDS instance or a stateful volume, it is a very bad afternoon.

The good news: every common state-moving task has a safe path that avoids a destroy/recreate. This guide walks through the five you will actually hit, and the habits that keep them boring.

Rule zero: back up first#

Before touching state, take a copy. With a local backend, terraform state pull writes the current state as JSON to stdout:

terraform state pull > backup.tfstate

If a migration goes sideways, you push the backup back:

terraform state push backup.tfstate

On a remote backend like S3, versioning gives you the same safety net for free, so long as you enabled it. Turn on bucket versioning and a restore is just rolling back to the prior object version. Do not skip this step because "it's a small change." Backups cost seconds; a corrupted state costs a rebuild.

1. Renaming or moving a resource address#

You refactored aws_instance.web into aws_instance.app. The infrastructure is identical, only the address changed. Two ways to tell Terraform.

The imperative way is terraform state mv:

terraform state mv aws_instance.web aws_instance.app

It works, but it runs once, off the record, on whoever's laptop happens to execute it. Teammates never see it in review.

The better way is a moved block. It lives in your config, gets code-reviewed like everything else, and is safe to re-run:

moved {
  from = aws_instance.web
  to   = aws_instance.app
}

Rename the resource block itself, add the moved block, and run terraform plan. Terraform reads the block, updates the address, and shows no changes to the resource. Once the change is merged and applied everywhere, you can delete the moved block. Prefer moved blocks over state mv whenever the source and target live in the same configuration. They are declarative, reviewable, and idempotent, which is exactly what you want when the alternative is silently deleting production.

2. Migrating the backend#

Moving from a local state file to S3, or between two remote backends, is a backend migration. Update the backend block, then let Terraform copy the state:

terraform init -migrate-state

Terraform detects the backend changed, asks whether to copy existing state to the new location, and moves it. A local-to-S3 config looks like this:

terraform {
  backend "s3" {
    bucket = "my-tf-state"
    key    = "prod/network.tfstate"
    region = "eu-west-1"
  }
}

After migration, confirm the state landed by running terraform plan and checking for zero diff. Then remove the old local terraform.tfstate so nobody edits the stale copy by accident. If you ever need a clean slate on the backend config without copying, terraform init -reconfigure skips the migration prompt, but that leaves the old state behind, so use it deliberately.

3. Splitting one big state into smaller ones#

A monolithic state that holds network, data, and app resources is slow to plan and risky to touch. Splitting it into per-domain states reduces blast radius.

The cleanest approach uses state mv with a target state file. From the source directory, move resources into a new state, then place that state under a new configuration:

terraform state mv -state-out=../network/terraform.tfstate \
  aws_vpc.main aws_vpc.main
terraform state mv -state-out=../network/terraform.tfstate \
  aws_subnet.public aws_subnet.public

Then, in the ../network directory, add matching resource blocks and run terraform plan. Zero diff means the resources now live in the new state and config, untouched. Back in the original directory, the moved resources are gone from state and should also be removed from that config.

An alternative is terraform state rm in the source followed by terraform import in the target. It works but is more error-prone, since you rebuild each address by hand and any typo shows up as a recreate. Reach for it only when the resources are moving across incompatible backends where -state-out is awkward.

4. Merging states#

Merging is splitting in reverse. Pull resources from one state into another with state mv, this time pointing -state-out at the destination state file, or run state mv from within the destination while pointing at the source. Copy the corresponding resource blocks into the destination config, run terraform plan, and confirm nothing changes. The order matters: move state first, add config, verify, then delete the emptied config and its now-orphaned state.

5. Moving a resource into or out of a module#

Module boundaries change the address, so Terraform needs to know. A moved block handles this too:

moved {
  from = aws_security_group.db
  to   = module.database.aws_security_group.db
}

The same block works in reverse to pull a resource out of a module. For count or for_each members, include the index or key in both addresses. This is where moved blocks really earn their keep, since module refactors touch many addresses at once and you want every one of them in the diff a reviewer sees.

The gotchas that bite#

State lock: Migrations acquire a lock. If a previous run crashed, the lock can linger and block you. Confirm no apply is running, then clear it with terraform force-unlock <LOCK_ID>. Never force-unlock while a real operation is in flight.

Provider and workspace mismatches: Moving state between configurations only works if both sides use compatible provider versions and the same workspace. A resource moved into a config with a newer provider schema can surface unexpected diffs. Line up provider versions before you move anything, and check you are in the right workspace with terraform workspace show.

Verify with a zero diff: The only proof a state move worked is terraform plan reporting no changes. Run it after every move. A clean plan means the address changed and the resource did not. Any proposed create or destroy means stop and investigate before you apply.

For the broader set of state and plan failures you might trip over along the way, see our Terraform error troubleshooting guide.

The call we'd make#

Default to moved blocks for anything inside a single configuration: renames, module moves, refactors. They ship through review, they re-run cleanly, and they leave a paper trail. Save terraform state mv for cross-state work like splitting and merging, always with -state-out. Back up before every move, verify with a zero-diff plan after, and treat a lingering lock as a signal to slow down rather than force through. State migrations feel scary, but done in this order they are just another reviewed change.