Skip to main content

Command: workspace new

The tofu workspace new command is used to create a new workspace.

Usage​

Usage: tofu workspace new [OPTIONS] NAME [DIR]

This command will create a new workspace with the given name. A workspace with this name must not already exist.

If the -state flag is given, the state specified by the given path will be copied to initialize the state for this new workspace.

The command-line flags are all optional. The supported flags are:

  • -lock=false - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace.

  • -lock-timeout=DURATION - Duration to retry a state lock. Default 0s.

  • -state=path - Path to an existing state file to initialize the state of this environment.

  • -var 'NAME=VALUE' - Sets a value for a single input variable declared in the root module of the configuration. Use this option multiple times to set more than one variable. Refer to Input Variables on the Command Line for more information.

  • -var-file=FILENAME - Sets values for potentially many input variables declared in the root module of the configuration, using definitions from a "tfvars" file. Use this option multiple times to include values from more than one file.

There are several other ways to set values for input variables in the root module, aside from the -var and -var-file options. Refer to Assigning Values to Root Module Variables for more information.

Example: Create​

Code Block
$ tofu workspace new example
Created and switched to workspace "example"!

You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "tofu plan" OpenTofu will not see any existing state
for this configuration.

Example: Create from State​

To create a new workspace from a pre-existing local state file:

Code Block
$ tofu workspace new -state=old.terraform.tfstate example
Created and switched to workspace "example".

You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "tofu plan" OpenTofu will not see any existing state
for this configuration.