---
description: The tofu workspace new command is used to create a new workspace.
---

# 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.

:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu workspace new`.
:::

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](../../../language/values/variables.mdx) 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](../plan.mdx#input-variables-on-the-command-line) for more information.

* `-var-file=FILENAME` - Sets values for potentially many
  [input variables](../../../language/values/variables.mdx) declared in the
  root module of the configuration, using definitions from a
  ["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
  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](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

## Example: Create

```
$ 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:

```
$ 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.
```