Workspaces in Visual Studio Code (2023)

A Visual Studio Code "workspace" is a collection of one or more folders that open in a VS Code window (snapshot). In most cases, you'll have a single folder open as your workspace, but depending on your development workflow, you can include more than one folder using an advanced configuration calledMulti-root workspaces.

The workspace concept allows VS Code to:

• Configure settings that apply only to a specific folder or folders but not to others.
• Insistworkandstart the debuggerconfigurations that apply only within this workspace.
• Save and restore user interface state associated with this workspace (for example, files being opened).
• Selectively enable or disable extensions for this workspace only.

You may see the terms "folder" and "workspace" used interchangeably in the VS Code documentation, issues, and community discussions. Think of a workspace as the root of a project that has additional VS Code knowledge and capabilities.

Note:It is also possible to open VS Code without a workspace. For example, when you open a new VS Code window by selecting a file from your platformFilemenu, you will not be in a workspace. In this mode, some of VS Code's features are reduced, but you can still open text files and edit them.

How do I open a VS Code "workspace"?

The easiest way to open a workspace is to use theFilemenu and selecting one of the available folder entries to open. Alternatively, if you launch VS Code from a terminal, you can pass the path to a folder as the first argument tocodecommand to open.

Single folder workspaces

You don't need to do anything to make a folder a VS Code workspace other than opening the folder with VS Code. Once a folder is opened, VS Code will automatically keep track of things like your open files and editor layout so that the editor is as you left it when you reopen that folder. You can also add other folder-specific configurations, such as workspace-specificSettings(in relation to global user settings),task definitions, andstart debuggingfiles (see below inworkspace settingsUnity).

A single folder workspace is opened inside VS Code

Multi-root workspaces

Multi-root workspacesis an advanced feature of VS Code that allows you to configure many different folders to be part of the workspace. Instead of opening a folder as your workspace, you'll open a.code-workspaceJSON file listing the workspace folders. For example:

{ "folders": [{ "path":"my-folder-a"},{ "path":"my-folder-b"}]}

A multi-root workspace opened in VS Code

Note:The visual difference of opening an envelope versus opening a.code-workspacethe file can be thin. To give you a hint that a.code-workspaceThe file is opened, some areas of the user interface (for example, the root of File Explorer) display an additional(Workplace)suffix next to the name.

(Video) VSCode Tutorial: How to creating a new workspace in Visual Studio Code

Untitled multi-root workspaces

It's easy to add or remove folders in your workspace. You can start by opening a folder in VS Code and then add more folders as you see fit. Unless you've already opened one.code-workspacefile, the first time you add a second folder to a workspace, VS Code will automatically create an "untitled" workspace. In the background, VS Code automatically maintains oneuntitled.workspace-codefile for you containing all folders and workspace settings from your current session. The workspace will remain "untitled" until you decide to save it to disk.

An untitled multi-root workspace opened in VS Code

Note:There really isn't any difference between an untitled workspace and a saved workspace, except that an untitled workspace is automatically created for your convenience and will always reset until you save it. We automatically delete untitled workspaces (after asking you for confirmation) when you close a window in which an untitled workspace is open.

Workspace settings

Workspace settings allow you to configure settings within the workspace you have open and always override global user settings. They are physically stored in a JSON file, and their location depends on whether you opened a folder as a workspace or whether you opened a.code-workspacefile.

I'm referring toSettingsdocumentation for a comprehensive explanation of setting fields and their file locations.

Single folder workspace settings

Workspace settings will be saved to.vscode/settings.jsonwhen you open a folder as a workspace.

The settings editor when a folder is opened as a workspace

Multi-root workspace settings

When you open one.code-workspaceas a workspace, all workspace settings will be added to the.code-workspacefile.

You can still configure settings per root folder and the settings editor will present a third settings field calledFolder settings:

The settings editor when a multi-root workspace is opened

The settings configured per folder will override the settings set in the.code-workspace.

Workspace tasks and startup configurations

Similar to howworkspace settingsare specific to a workspace, tasks and startup configurations can also be set to a workspace. Depending on whether you have opened a folder as a workspace or a.code-workspacefile, the location of the working and startup configurations of the workspace will either be inside the.vscodefolder or inside.code-workspacefile. Additionally, task and startup configurations can always be set at the single-folder level, even when you've opened.code-workspacefile.

I'm referring todutiesanddebuggingchapters for a more comprehensive overview of how to use tasks and launch configurations in VS Code.

Common questions

What is the benefit of multi-root workspace over single folder?

The most obvious advantage is that a multi-root workspace allows you to work with multiple projects that may not be stored in the same parent folder on disk. You can select folders from anywhere to add to the workspace.

Even if you work primarily on a folder-based project, you can still benefit from using it.code-workspacearchives. You can save a lot.code-workspacefiles within the folder to provide a scope folder view of certain aspects of the project depending on the scenario (for exampleclient.code-workspace,server.code-workspaceto filter out irrelevant folders from File Explorer). From.code-workspacefiles support relative paths for thefolderssection, these workspace files will work for everyone no matter where the folder is stored.

Finally, if for some projects you want to apply the same set of workspace settings or task/launch configurations, consider adding them to.code-workspacefile and add/remove these folders from this workspace.

Why does VS Code reset all untitled workspaces on restart?

Untitled workspaces are designed to be something you have to explicitly decide to keep or not. The first time an untitled workspace is created, VS Code adds the specified folders to the workspace file and also all existing workspace settings. This user data is always restored and displayed in a VS Code window until the untitled workspace is saved or deleted.

How do I delete an untitled workspace?

You can delete an untitled workspace by closing its window and dismissing the prompt to save the untitled workspace.

I can use a multi-root workspace without folders

It is possible to leave itfolderspart of a.code-workspacefile is empty so you end up with an instance of VS Code that doesn't show any root folders. You can still save workspace settings and even tasks or launch configurations in this case.

Does VS Code support projects or solutions?

VS Code does not have the concept of "project" or "solution" as sometimes defined in other development tools, for example Visual Studio IDE. You may see the term "project" used in the VS Code documentation, but it usually means "the thing you're working on." Depending on the programming language or framework, the toolkit itself may support something called a "project" to help you define build configurations or list included files.

6/8/2023