Skip to main content
In this lesson we’ll explore Terraform workspaces — a native feature for managing multiple environments (for example: development, QA, and production) from a single Terraform configuration directory. Problem: you want to deploy the same Terraform code (main.tf, providers.tf, etc.) to multiple environments without duplicating files and while keeping each environment’s state isolated. The naive approach — copying the configuration into dev/, qa/, and prod/ folders — quickly becomes hard to maintain and error-prone. Solution: Terraform workspaces let you keep one set of configuration files and create multiple named workspaces. Each workspace maintains its own state, so you can manage separate environments without duplicating code.
A slide diagram showing a single Terraform working directory (main.tf, providers.tf) using separate workspaces (Dev, QA, Testing), each with its own terraform.tfstate. Each workspace maps to a corresponding environment account (Development, QA, Testing) and the slide lists benefits like same configuration, isolated state, and no code duplication.
This approach eliminates code duplication and ensures that state for each environment is kept separate. What is a workspace?
  • A workspace is a named container for a separate instance of your Terraform state.
  • Each workspace stores its own state; when you switch to a workspace, Terraform reads and writes that workspace’s state.
  • Every Terraform project begins in the default workspace (created automatically when you run terraform init).
When people say “import a resource into your workspace” or refer to “your workspace”, they mean the currently selected workspace in the working directory — i.e., the state Terraform is using right now. Switching workspaces changes which state file is read/written while keeping the same configuration files. If you switch to a newly created workspace with no deployed resources, state inspection commands will show there is no state yet:
Important distinction: workspaces isolate state, not configuration. Workspaces do not automatically change providers, credentials, or regions. If you need different accounts or regions per environment, combine workspaces with variables, provider aliasing, or different backend configurations. Otherwise you risk creating multiple environment resources in the same cloud account. How Terraform stores workspace state on disk (local backend) When using the local backend:
  • The default workspace state is stored as terraform.tfstate in the project root.
  • Additional workspaces are stored under terraform.tfstate.d/, with one subdirectory per workspace containing a terraform.tfstate file.
Note: If you use a remote backend (S3, AzureRM, GCS, or Terraform Cloud/Enterprise), workspace state management and naming are handled by the backend and will not necessarily appear under terraform.tfstate.d/ locally.
A diagram titled "How Workspaces Store State Files" showing a project folder with main.tf and providers.tf, terraform.tfstate as the default workspace, and a terraform.tfstate.d directory containing dev/ and testing/ workspace state folders.
Example filesystem layout (local backend):
Terraform automatically reads/writes the appropriate state file for whichever workspace is selected. Common workspace CLI commands Use terraform workspace subcommands to manage CLI workspaces. The table below summarizes the most common operations. Example session:
Notes on deletion:
  • You cannot delete the default workspace.
  • You cannot delete the workspace you’re currently using; switch to another workspace first (for example default).
You cannot delete the workspace you are currently using. Switch to another workspace (for example default) before attempting to delete a workspace.
CLI workspaces vs HCP/Enterprise workspaces The word “workspace” is used for two different concepts in the Terraform ecosystem. They are not interchangeable:
When you see workspace, check context: is it a CLI workspace (managed with terraform workspace ...) or an HCP/Terraform Enterprise workspace (a cloud-hosted workspace with VCS integration, runs, variables, and team controls)? They solve different problems.
Best practices and gotchas
  • Use workspaces for simple environment separation where state isolation is sufficient and configuration remains the same.
  • For different cloud accounts, regions, or provider credentials per environment, combine workspaces with provider aliasing, environment-specific variables, or a different backend configuration — otherwise you might unintentionally create resources in the same account.
  • Consider using a remote backend (S3, GCS, Azure Blob, or Terraform Cloud) for team collaboration and centralized state storage.
  • Treat workspaces as state isolation only — not a replacement for full environment separation if your environments need differing configurations or access controls.
Resources and further reading Summary
  • Terraform workspaces let you manage multiple environments (each with its own isolated state) from a single configuration directory, removing the need for duplicate configuration files.
  • Every project starts in the default workspace; additional workspaces store state under terraform.tfstate.d/ when using the local backend (remote backends vary).
  • Manage workspaces with terraform workspace list, new, select, show, and delete.
  • Remember the distinction between CLI workspaces and HCP/Terraform Enterprise workspaces — they are different tools for different use cases.

Watch Video

Practice Lab