| --- |
| page_title: terraform state push command reference |
| description: The `terraform state push` command uploads a state file to the Terraform state. |
| --- |
| |
| # `terraform state push` command |
| |
| The `terraform state push` command uploads a local state file to [remote state](/terraform/language/state/remote) or a local state. We only recommend using this command when you must manually modify the remote state. |
| |
| ## Usage |
| |
| Usage: `terraform state push [options] PATH` |
| |
| This command pushes the state specified by PATH to the currently |
| configured [backend](/terraform/language/backend). |
| |
| If PATH is "-" then the state data to push is read from stdin. This data |
| is loaded completely into memory and verified prior to being written to |
| the destination state. |
| |
| -> **Note:** Terraform state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `terraform state push | Set-Content terraform.tfstate`. |
| |
| Terraform will perform a number of safety checks to prevent you from |
| making changes that appear to be unsafe: |
| |
| - **Differing lineage**: If the "lineage" value in the state differs, |
| Terraform will not allow you to push the state. A differing lineage |
| suggests that the states are completely different and you may lose |
| data. |
| |
| - **Higher remote serial**: If the "serial" value in the destination state |
| is higher than the state being pushed, Terraform will prevent the push. |
| A higher serial suggests that data is in the destination state that isn't |
| accounted for in the local state being pushed. |
| |
| Both of these safety checks can be disabled with the `-force` flag. |
| **This is not recommended.** If you disable the safety checks and are |
| pushing state, the destination state will be overwritten. |
| |
| For configurations using the [HCP Terraform CLI integration](/terraform/cli/cloud) or the [`remote` backend](/terraform/language/backend/remote) |
| only, `terraform state push` |
| also accepts the option |
| [`-ignore-remote-version`](/terraform/cli/cloud/command-line-arguments#ignore-remote-version). |
