June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Network Infrastructure
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform CLI

  • Overview
  • Basic CLI Features
    • Overview
    • init
    • get
    • Overview
    • plan
    • apply
    • destroy
    • Overview
    • login
    • logout
    • Overview
    • console
    • fmt
    • validate
    • 0.13upgrade
    • 0.12upgrade
    • Overview
    • graph
    • output
    • show
    • state list
    • state show
    • Overview
    • import
    • Usage Tips
    • Resource Importability
    • Overview
    • Resource Addressing
    • state
      • Overview
      • state list
      • state show
      • refresh
      • Overview
      • taint
      • untaint
      • Overview
      • state mv
      • state rm
      • state replace-provider
      • Overview
      • state pull
      • state push
      • force-unlock
    • Overview
      • Overview
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • Overview
    • Plugin Signing
    • providers
    • version
    • providers lock
    • providers mirror
    • providers schema
    • Overview
    • CLI Configuration
    • Environment Variables
    • Overview
    • Terraform Cloud Settings
    • Initializing and Migrating
    • Command Line Arguments
    • Running Terraform in Automation
    • GitHub Actions
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
    • providers
    • providers lock
    • providers mirror
    • providers schema
    • push (deprecated)
    • refresh
    • show
    • state
    • state list
    • state mv
    • state pull
    • state push
    • state replace-provider
    • state rm
    • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
    • workspace
    • workspace list
    • workspace select
    • workspace new
    • workspace delete
    • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
      • providers
      • providers lock
      • providers mirror
      • providers schema
    • push (deprecated)
    • refresh
    • show
      • state
      • state list
      • state mv
      • state pull
      • state push
      • state replace-provider
      • state rm
      • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
      • workspace
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • Overview
    • Credentials Helpers
    • Debugging Terraform
    • Module Registry Protocol
    • Provider Network Mirror Protocol
    • Provider Registry Protocol
    • Resource Graph
    • Resource Lifecycle
    • Login Protocol
    • JSON Output Format
    • Remote Service Discovery
    • Provider Metadata
    • APT Packages for Debian and Ubuntu
    • Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux
  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Command: state rm

The main function of Terraform state is to track the bindings between resource instance addresses in your configuration and the remote objects they represent. Normally Terraform automatically updates the state in response to actions taken when applying a plan, such as removing a binding for a remote object that has now been deleted.

You can use terraform state rm in the less common situation where you wish to remove a binding to an existing remote object without first destroying it, which will effectively make Terraform "forget" the object while it continues to exist in the remote system.

»Usage

Usage: terraform state rm [options] ADDRESS...

Terraform will search the state for any instances matching the given resource address, and remove the record of each one so that Terraform will no longer be tracking the corresponding remote objects.

This means that although the objects will still continue to exist in the remote system, a subsequent terraform plan will include an action to create a new object for each of the "forgotten" instances. Depending on the constraints imposed by the remote system, creating those objects might fail if their names or other identifiers conflict with the old objects still present.

This command also accepts the following options:

  • -dry-run - Report all of the resource instances that match the given address without actually "forgetting" any of them.

  • -lock=false - 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 - Unless locking is disabled with -lock=false, instructs Terraform to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds.

For configurations using the Terraform Cloud CLI integration or the remote backend only, terraform state rm also accepts the option -ignore-remote-version.

For configurations using the local state rm only, terraform state rm also accepts the legacy options -state, -state-out, and -backup.

»Example: Remove all Instances of a Resource

The following example will cause Terraform to "forget" all of the instances of the packet_device resource named "worker".

$ terraform state rm 'packet_device.worker'
$ terraform state rm 'packet_device.worker'

A resource that doesn't use count or for_each has only one instance, so this is also the appropriate syntax to select that single instance.

»Example: Remove all Instances of a Resource in a Module

To select a resource that you've defined in a child module you must specify the path of that module as part of the resource address:

$ terraform state rm 'module.foo.packet_device.worker'
$ terraform state rm 'module.foo.packet_device.worker'

»Example: Remove all Instances of all Resources in a Module

The following example will cause Terraform to "forget" all of the instances associated with all resources defined in all instances of the module named foo:

$ terraform state rm 'module.foo'
$ terraform state rm 'module.foo'

»Example: Remove a Particular Instance of a Resource using count

A resource defined with the count meta-argument has multiple instances that are each identified by an integer. You can select a particular instance by including an explicit index in your given address:

$ terraform state rm 'packet_device.worker[0]'
$ terraform state rm 'packet_device.worker[0]'

Brackets ([, ]) have a special meaning in some shells, so you may need to quote or escape the address in order to pass it literally to Terraform. The above shows the typical quoting syntax for Unix-style shells.

»Example: Remove a Particular Instance of a Resource using for_each

A resource defined with the for_each meta-argument has multiple instances that are each identified by an string. You can select a particular instance by including an explicit key in your given address.

However, the syntax for strings includes quotes and the quote symbol often has special meaning in command shells, so you'll need to use the appropriate quoting and/or escaping syntax for the shell you are using. For example:

Unix-style shells, such as on Linux or macOS:

$ terraform state rm 'packet_device.worker["example"]'
$ terraform state rm 'packet_device.worker["example"]'

Windows Command Prompt (cmd.exe):

$ terraform state rm packet_device.worker[\"example\"]
$ terraform state rm packet_device.worker[\"example\"]

PowerShell:

$ terraform state rm 'packet_device.worker[\"example\"]'
$ terraform state rm 'packet_device.worker[\"example\"]'
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager