terraform workspace Command Reference

Multiple named states from one configuration, one per environment.

terraform workspace manages named workspaces, each with its own state, backed by the same configuration and backend. They are handy for ephemeral or per-branch environments.

What it does

Workspaces let a single configuration hold separate states (default, staging, prod). new creates one, select switches to it, and list shows them with the active one marked. terraform.workspace exposes the current name to your config.

Common flags and usage

new NAME: create and switch to a new workspace
select NAME: switch to an existing workspace
select -or-create NAME: switch, creating if absent (Terraform 1.4+)
list: list all workspaces (current marked with *)
show: print the active workspace name

Example

shell

# Pick a per-branch workspace, creating it on first run
terraform workspace select -or-create "ci-${GITHUB_REF_NAME}"
terraform plan -input=false -out=tfplan

In CI

Use workspace select -or-create so a pipeline never fails on a workspace that does not exist yet. Confirm the backend supports workspaces (local and S3 do; some do not).

Key takeaways

Workspaces give one configuration multiple isolated states.
select -or-create avoids a does not exist failure on first run.
terraform.workspace exposes the active name for per-env config logic.