terraform/website/docs/cli/commands/workspace/new.html.md

---
layout: "docs"
page_title: "Command: workspace new"
sidebar_current: "docs-commands-workspace-sub-new"
description: |-
  The terraform workspace new command is used to create a new workspace.
---

# Command: workspace new

The `terraform workspace new` command is used to create a new workspace.

## Usage

Usage: `terraform 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.

## Example: Create

```
$ terraform 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 "terraform plan" Terraform 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:

```
$ terraform 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 "terraform plan" Terraform will not see any existing state
for this configuration.
```