Skip to main content
The terraform state mv command moves items in the Terraform state, allowing you to rename resources or move them between modules.

​
Synopsis

Move an item in the state.

​
Usage

terraform state mv [options] SOURCE DESTINATION
This command moves an item matched by the source address to the destination address. This command can also move items to a destination address in a completely different state file. This can be used for simple resource renaming, moving items to and from a module, moving entire modules, and more. Because this command can also move data to a completely new state, it can also be used for refactoring one configuration into multiple separately managed Terraform configurations. This command will output a backup copy of the state prior to saving any changes. The backup cannot be disabled. Due to the destructive nature of this command, backups are required. If you’re moving an item to a different state file, a backup will be created for each state file.

​
Options

​
-dry-run
boolean
If set, prints out what would’ve been moved but doesn’t actually move anything.
​
-lock
boolean
default:"true"
Don’t hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace.
​
-lock-timeout
duration
default:"0s"
Duration to retry a state lock.
​
-ignore-remote-version
boolean
A rare option used for the remote backend only. See the remote backend documentation for more information.
​
-state
string
Path to the source state file. Legacy option supported for the local backend only.
​
-state-out
string
Path to the destination state file. Legacy option supported for the local backend only.
​
-backup
string
default:"-"
Path where Terraform should write the backup for the source state. Legacy option supported for the local backend only.
​
-backup-out
string
default:"-"
Path where Terraform should write the backup for the destination state. Legacy option supported for the local backend only.

​
Arguments

​
SOURCE
string
required
The source address of the resource to move. Can be a resource instance, entire resource, or module.
​
DESTINATION
string
required
The destination address where the resource should be moved.

​
Examples

​
Rename a resource

Rename a resource from one name to another: 
terraform state mv aws_instance.old_name aws_instance.new_name
Output: 
Move "aws_instance.old_name" to "aws_instance.new_name"
Successfully moved 1 object(s).

​
Move a resource into a module

Move a resource from the root module into a child module: 
terraform state mv aws_instance.web module.servers.aws_instance.web

​
Move a resource out of a module

Move a resource from a module to the root: 
terraform state mv module.servers.aws_instance.web aws_instance.web

​
Move an entire module

Move all resources from one module to another: 
terraform state mv module.old_module module.new_module

​
Move resource to different state file

Move a resource to a different state file: 
terraform state mv -state-out=other.tfstate aws_instance.web aws_instance.web

​
Dry run

Preview what would be moved without making changes: 
terraform state mv -dry-run aws_instance.old aws_instance.new
Output: 
Would move "aws_instance.old" to "aws_instance.new"

​
Move indexed resource

Move a resource instance with an index: 
terraform state mv 'aws_instance.web[0]' 'aws_instance.web[1]'

​
Move to resource with count

Move a single instance to become part of a counted resource: 
terraform state mv aws_instance.web 'aws_instance.web[0]'

​
Common Use Cases

​
Refactor resource names

When renaming resources in your configuration, use state mv to update the state to match without destroying and recreating the resources.

​
Reorganize modules

Move resources into or out of modules as your infrastructure organization evolves.

​
Split configurations

When splitting a monolithic Terraform configuration into multiple separate configurations, use state mv with -state-out to move resources between state files.

​
Add or remove count/for_each

When adding count or for_each to an existing resource, use state mv to move the single instance to the appropriate indexed location.

​
Module refactoring

Rename modules or reorganize module hierarchies without recreating infrastructure.

Build docs developers (and LLMs) love

Get started for freeTalk to us