How to Create and Use a Multi-Root Workspace in VS Code

A multi-root workspace is a VS Code window that contains more than one root folder. Add the related folders, save the setup as a .code-workspace file, and then use them together without moving them under one parent directory.

Add folders to a workspace

Save the workspace

An untitled workspace has not yet been saved to a permanent location. To save it, go to File > Save Workspace As.

Choose a location and a file name. The convention is to use a name like my-project.code-workspace.

Click Save.

The workspace file name appears in the File Explorer. To reopen it later, use File > Open Workspace and select the file, double-click it in your operating system's file manager, or choose it from File > Open Recent, where saved workspaces have a (Workspace) suffix.

Understand the workspace file

A workspace file is JSON. Open it in VS Code to see and edit the structure directly.

Here is a minimal example:

json

{
  "folders": [
    { "path": "./frontend" },
    { "path": "./backend" }
  ]
}

Each folder object can also have an optional name field. Use it when the directory name alone does not clearly identify that root in the File Explorer.

Configure settings across folders

In a multi-root workspace, settings exist at three levels:

For the same setting type, folder settings override workspace settings, and workspace settings override user settings. Language-specific settings have their own precedence, so compare like-for-like scopes when a value appears not to apply.

To edit each level in the Settings editor, use the tabs at the top: User, Workspace, and the folder name tabs. You can also run the commands Preferences: Open Workspace Settings and Preferences: Open Folder Settings from the Command Palette.

Not all settings work at the folder level. Settings that affect the entire editor window, like zoom level, are only available at the workspace scope. Folder-level unsupported settings appear grayed out in the Settings editor.

Search across all folders

Global search (Ctrl+Shift+F / Cmd+Shift+F) scans all root folders and groups results by folder name.

To limit search to one folder, type the folder path prefix in the files to include field. For example, ./client/**/*.ts searches TypeScript files only inside the folder named client.

Source Control with multiple repositories

When each root folder has its own Git repository, the Source Control view shows a SOURCE CONTROL PROVIDERS section listing each repository. Select one to see its changes, staged files, and commit history.

Use Ctrl+Click or Shift+Click to select multiple repositories. Their details appear as separate regions below the repository list.

Debug across folders

VS Code collects debug configurations from every folder and lists them in the Run and Debug dropdown. Each configuration shows the folder name as a suffix.

Workspace-level launch configurations go inside the workspace file under a launch key.

json

{
  "folders": [{ "path": "./client" }, { "path": "./server" }],
  "launch": {
    "compounds": [
      {
        "name": "Launch Full Stack",
        "configurations": ["Launch Client", "Launch Server"]
      }
    ]
  }
}

For more details, see how to debug multiple services with compound configurations.

If you are new to workspaces, read VS Code folder vs workspace first.

Tasks across folders

VS Code discovers tasks from each folder's tasks.json files, plus auto-detected tasks from npm, gulp, grunt, and TypeScript project files. The Terminal > Run Task dropdown shows each task with its folder name as a suffix.

Workspace-level tasks go inside the workspace file under a tasks key. Only shell and process type tasks are supported there.

Open a multi-root workspace from the command line

Use the --add flag to add folders to the last active VS Code window:

bash

code --add ./frontend ./backend

The command adds the folders to the last active VS Code window. Confirm success by checking that each path appears as a root in the File Explorer.

You can also open a saved workspace file directly:

bash

code my-project.code-workspace

How to go back to a single folder

If a root no longer belongs in the workspace, right-click it and choose Remove Folder from Workspace. This removes the root from the workspace without deleting its files from disk.

To return to a normal single-folder workspace, use File > Close Workspace, then open the folder directly with File > Open Folder.