terraform workspace delete
The terraform workspace delete command deletes a workspace.
Usage
terraform [global options] workspace delete [OPTIONS] NAME
Description
This command deletes the specified workspace and its associated state. By default, Terraform prevents deletion of workspaces that contain managed resources to protect against accidental data loss.
Deleting a workspace removes Terraform’s ability to track and manage the infrastructure in that workspace. If resources still exist, you’ll need to manage or delete them manually outside of Terraform.
Arguments
NAME - (Required) The name of the workspace to delete. Cannot be empty.
Options
-
-force - Remove a workspace even if it contains managed resources. Use with extreme caution. Default: false
When using -force, Terraform will forget about managed resources, which must then be deleted manually outside of Terraform.
-
-lock=true - Lock the state file during the operation. Set to false to disable locking. Default: true
Setting -lock=false is dangerous if others might concurrently run commands against the same workspace.
-
-lock-timeout=0s - Duration to wait for a state lock to be released before timing out. Accepts values like 10s or 5m. Default: 0s (no retry)
Examples
Delete an Empty Workspace
terraform workspace delete development
Deleted workspace "development"!
Force Delete a Non-Empty Workspace
terraform workspace delete -force staging
Deleted workspace "staging"!
WARNING: "staging" was non-empty.
The resources managed by the deleted workspace may still exist,
but are no longer manageable by Terraform since the state has
been deleted.
Delete with Lock Timeout
terraform workspace delete production -lock-timeout=30s
Behavior Notes
Non-Empty Workspace Protection
If a workspace contains managed resources and you don’t use the -force flag, the command will fail with a detailed error listing all managed resources:
Error: Workspace is not empty
Workspace "staging" is currently tracking the following resource instances:
- aws_instance.web
- aws_s3_bucket.data
- aws_vpc.main
Deleting this workspace would cause Terraform to lose track of any associated
remote objects, which would then require you to delete them manually outside
of Terraform. You should destroy these objects with Terraform before deleting
the workspace.
If you want to delete this workspace anyway, and have Terraform forget about
these managed objects, use the -force option to disable this safety check.
Cannot Delete Current Workspace
You cannot delete the workspace that is currently selected. Switch to another workspace first:
Workspace "production" is your active workspace.
You cannot delete the currently active workspace. Please switch
to another workspace and try again.
terraform workspace select default
terraform workspace delete production
Cannot Delete Default Workspace
The default workspace cannot be deleted:
Cannot delete the default workspace
Non-Existent Workspace
If you attempt to delete a workspace that doesn’t exist, the command will fail:
Workspace "staging" doesn't exist.
You can create this workspace with the "new" subcommand
or include the "-or-create" flag with the "select" subcommand.
Empty String Name
You cannot delete a workspace with an empty string as the name:
Expected a workspace name as an argument, instead got an empty string: ""
Best Practices
-
Destroy resources first: Always run
terraform destroy before deleting a workspace to properly clean up infrastructure.
terraform workspace select staging
terraform destroy
terraform workspace select default
terraform workspace delete staging
-
Verify workspace contents: Use
terraform state list to check what resources are managed before deletion.
-
Avoid
-force in automation: The -force flag should only be used when you’re certain about the consequences.
Exit Codes
0 - Success1 - Error (e.g., workspace doesn’t exist, workspace is current, workspace contains resources, workspace is default, failed to load backend)