Describe the local backend

You run terraform apply in a directory with no backend and no cloud block, and a file named terraform.tfstate appears beside your .tf files. You already know Terraform keeps that state to map your configuration to real resources; what this section adds is exactly where the local backend puts the file, how it locks it, and how workspaces and a few legacy flags move it.

The local backend is a real default, not 'no backend'

A common misread is that a configuration without a backend block has no backend at all. It has one. Terraform uses a backend called local by default, and the local backend type stores state as a local file on disk^[1]. More precisely, that backend stores state on the local filesystem, locks that state using system APIs, and performs operations locally^[2]. Because it is a genuine backend, you can also write it out explicitly:

terraform {
  backend "local" {
    path = "relative/path/to/terraform.tfstate"
  }
}

terraform.tfstate and its backup

By default, Terraform stores each workspace's state in a local file named terraform.tfstate, and a backup of the previous state in terraform.tfstate.backup^[3]. A workspace here is just a named, independent state in the same directory; the default one lands in this top-level file, and the workspaces section below covers the rest. The file is JSON, it sits in the root module's working directory, and a successful apply rewrites it to record the change it just made. Storing state locally requires no additional configuration^[3], which is exactly why it is the default you get for free.

Its two arguments: path and workspace_dir

The local backend exposes only two optional arguments. path is the path to the state file and defaults to terraform.tfstate relative to the root module^[2]; set it to rename or relocate the file. workspace_dir is the path to non-default workspaces^[2]; it defaults to the terraform.tfstate.d directory covered in the workspaces section below.

Locking is built in

State locking is not exclusive to remote backends. The local backend acquires its lock through operating-system file-locking APIs^[2] rather than an external service, so two Terraform runs on the same machine cannot write the file at once. That lock lives on one machine, which is the key limitation: it guards a single operator, not teammates running Terraform from different hosts.

The figure shows the whole picture. A configuration with no backend block resolves to the local backend, which runs operations on your machine and keeps state, plus its backup, in files on local disk.

When you use the local backend, three command-line flags point the state read, the state write, and the backup at explicit filenames. Treat them as historical: this section of the docs describes legacy features preserved for backward compatibility that HashiCorp no longer recommends^[2]. Know them anyway, because an exam item can hinge on what they do and on how they interact with workspaces.

The three flags map onto read, write, and backup

• -state=FILENAME overrides the state filename when reading the prior state snapshot^[2].
• -state-out=FILENAME overrides the state filename when writing new state snapshots^[2]. If you set -state without -state-out, Terraform uses the -state filename for both, overwriting the input file when it writes a new snapshot^[2].
• -backup=FILENAME overrides the backup filename the local backend would otherwise choose^[2]. The default backup is the state file's name with a .backup suffix (so terraform.tfstate.backup for the default file), and -backup=-, a single ASCII dash, disables the creation of backup files altogether^[2].

They bypass workspace file selection

Here is the trap. These flags name state files directly, so when you pass them the selected workspace no longer determines the state filename^[4]. Passing -state does not switch workspaces and it does not read a workspace's terraform.tfstate.d file; it steps around workspace-based file selection entirely, which means you must manage a distinct filename per workspace yourself. Prefer setting path and using workspaces over reaching for these flags.

The figure traces one operation with the flags set: Terraform reads prior state from the -state file, writes the new snapshot to the -state-out file, and writes a copy to the -backup file unless -backup=- turns it off.

Terraform workspaces let one working directory hold several independent states, and with the local backend each workspace is just a different file on disk. Every initialized working directory starts with one workspace named default^[5], and Terraform starts with a single, default workspace named default that you cannot delete^[4].

The default workspace uses the plain path; others live under terraform.tfstate.d

The rule to remember: only non-default workspaces get a subdirectory. The default workspace stores its state directly at terraform.tfstate (or your configured path). Every other workspace's state goes under a directory Terraform names terraform.tfstate.d^[5], one child per workspace, as terraform.tfstate.d/<workspace_name>/terraform.tfstate. The workspace_dir backend argument^[2] overrides that parent directory name when you need the files elsewhere.

Managing workspaces

The terraform workspace command family manages these named states:

Subcommand	What it does
terraform workspace new NAME	Creates a new workspace[6] and switches to it
terraform workspace select NAME	Switches to an existing workspace
terraform workspace list	Lists all workspaces, marking the current one with an asterisk[7]
terraform workspace show	Outputs the current workspace name[8]
terraform workspace delete NAME	Deletes an empty workspace

Deletion has guardrails: the target must not be your current workspace and must not still be tracking resources unless you pass -force^[9], and the default workspace cannot be deleted at all. Inside configuration, read the active workspace with the terraform.workspace value^[4].

The figure shows the on-disk layout for a directory with three workspaces: default at the top-level terraform.tfstate, and prod and staging each under their own terraform.tfstate.d subdirectory.

TA-004 items on the local backend usually test a misconception, and no cloud-specific knowledge is required. Each pattern below pairs the tempting wrong answer with the plain behavior established above.

'No backend block' does not mean 'no backend'

When a stem shows a configuration with no backend and asks where state goes, the answer is the local backend and terraform.tfstate on disk, because local is the default backend^[1]. An option claiming Terraform refuses to store state, or keeps it only in memory, is the trap.

Locking is not a remote-only feature

If an item implies you must adopt a remote backend just to get state locking, that is wrong. The local backend already locks state using system APIs^[2]. The real limit is scope: that lock covers one machine, so the reason to move to a remote backend is shared state across a team, not the absence of any lock.

-state does not change workspaces

A stem that treats -state=FILENAME as a way to switch workspaces is testing the legacy-flag trap. Passing the legacy flags means the selected workspace no longer determines the state filename^[4], so -state bypasses workspace selection rather than performing it; use terraform workspace select to switch, and -state only when you deliberately want to name a file.

Only non-default workspaces use terraform.tfstate.d

If asked where the default workspace's state lives, it is the top-level terraform.tfstate, not a subdirectory. Only non-default workspaces are filed under terraform.tfstate.d^[5] as terraform.tfstate.d/<name>/terraform.tfstate; an answer that puts every workspace, including default, inside that directory is wrong.

You cannot delete the current or default workspace

When a scenario tries to delete the workspace you are on, or the default workspace, the operation fails. terraform workspace delete requires that the target is not your current workspace and is not still tracking resources unless -force is set^[9], and the default workspace cannot be deleted^[4] at all.