Multi-root workspaces in Visual Studio Code (2023)

You can work with multiple project folders in Visual Studio Code with workspaces that have multiple roots. This can be useful when working on several related projects at the same time. For example, you may have a repository of product documentation that you would like to keep up to date when you update the product source code.

Multi-root workspaces in Visual Studio Code (1)

note: If you want to learn more about VS Code's "workspace" concept, you can check this outWhat is a VS Code "workspace"?Unless you explicitly create a multi-root workspace, a "workspace" is just the single root folder of your project.

add folder

It's easy to add another folder to your existing workspace. There are several gestures for adding folders:

Add folder to workspace

Thefile>Add folder to workspaceThe command opens an Open Folder dialog box to select the new folder.

Multi-root workspaces in Visual Studio Code (2)

Once a root folder is added, Explorer will show the new folder as the root in File Explorer. You can right-click any of the root folders and use the context menu to add or remove folders.

Multi-root workspaces in Visual Studio Code (3)

File Explorer should work and behave as before. You can move files between root folders and use all typical file operation actions provided in context menu and explorer view.

Settings likefiles.excludeare supported for each root folder if configured and for all folders if configured as a global user setting.

drag and drop

You can add folders to a workspace using drag and drop. Drag a folder into File Explorer to add it to the current workspace. You can even select and drag multiple folders.

note: Dragging a single folder into the VS Code editor area still opens the folder in single folder mode. Dragging and dropping multiple folders into the editor area creates a new multi-root workspace.

You can also rearrange folders in the workspace using drag-and-drop.

Multi-select native file open dialogs

Opening multiple folders with your platform's native file open dialog creates a multi-root workspace.

(Video) VS Code tips — Multi-root workspaces

command line --add

Add one or more folders to the last active VS Code instance for a multi-root workspace.

code --add vscode vscode-docs

remove folder

With you can remove a folder from a workspaceRemove folder from workspacecontext menu command.

workspace file

When you add multiple folders, they are initially placed in a titled workspaceUNTITLED WORKSPACEand this name persists until you save the workspace. You don't need to save a workspace until you want it in a permanent location, such as a desktop. B. on your desktop. Unnamed workspaces exist as long as the VS Code instance using them is open. Once you've completely closed an instance with an unnamed workspace, you'll be prompted to save it if you intend to open it again in the future:

Multi-root workspaces in Visual Studio Code (4)

When you save your workspace, a.code workspaceFile and the file name are displayed in File Explorer.

Save workspace as...

If you want to move your workspace file to a new location, you can use thefile>Save Workspace AsCommand that automatically sets the correct folder paths relative to the new workspace file location.

Open workspace files

To reopen a workspace, you can:

  • Double-click the.code workspacefile in your platform explorer.
  • Use thefile>Open workspacecommand and select the workspace file.
  • Select the workspace from thefile>Open Recent(⌃R(Windows, LinuxStrg+R)) List.
    • Workspaces have one(Workplace)Suffix to distinguish them from folders.

Multi-root workspaces in Visual Studio Code (5)

As well asclose folderWhen a single folder is open in VS Code, there is oneClose workspace(⌘K F(Windows, LinuxCtrl+K F)) command to close the active workspace.

Workspace file schema

The scheme of.code workspaceis pretty easy. You have a set of folders with either absolute or relative paths. Relative paths are better when you want to share workspace files.

You can override the display name of your folders withNameattribute to give folders more meaningful names in Explorer. For example, you could name your project folders like "Product" and "Documentation" to easily identify the contents by folder name:

{ "Binder": [{ // Source code "Name":"Product", "Away":"vscode"},{ // Documents and release notes "Name":"Documentation", "Away":"vscode-docs"},{ // Yeoman extension generator "Name":"extension generator", "Away":"vscode-generator-code"}]}

resulting in the following Explorer display:

Multi-root workspaces in Visual Studio Code (6)

As you can see in the example above, you can add comments to your workspace files.

The workspace file can also be workspaceglobal settingsunderIdeasAndRenewal Recommendationsunderextensions, which we will discuss below.

Multi-root workspaces in Visual Studio Code (7)

(Video) VSCode Tutorial #14 - Multi-root Workspace

General user interface


There are few changes to the VS Code UI when using multi-root workspaces, mainly to make files unique between folders. For example, if there is a naming conflict between files in multiple folders, VS Code puts the folder name in the tabbed headers.

Multi-root workspaces in Visual Studio Code (8)

If you want to always see the folder displayed in the tabbed header, you can use theworkbench.editor.labelFormat Attitude"medium" or "long" values ​​to show the folder or full paths.


VS Code UI like thatEDITORS OPENAndOpen quickly(⌘P(Windows, LinuxCtrl+P)) lists contain the folder name.

Multi-root workspaces in Visual Studio Code (9)

If you use oneFile Icon Designand the active theme supports it, you will see a special workspace icon.

Below are the workspace icons from the built-inMinimal (Visual Studio-Code)File Icon Theme:

Multi-root workspaces in Visual Studio Code (10)


VS Code features like global search work across all folders and group search results by folder.

Multi-root workspaces in Visual Studio Code (11)

If you have a multi-root workspace open, you can use to search in a single root folder./syntax in theinsert filesCrate. For example when you enter./projekt1/**/*.txt, that will search for all.txtfiles under theproject 1/root directory.


If there are multiple root folders in a workspace, it is possible to.vscodeFolder in each root folder that defines the settings to apply to that folder. To avoid setting collisions, only resource settings (file, folder) are applied when using a multi-root workspace. Settings that affect the entire editor (e.g. UI layout) are ignored. For example, two projects cannot both set the zoom level.

User preferences are supported as with single-folder projects, and you can also set global workspace preferences that apply to all folders in your multi-root workspace. Global workspace settings are stored in your.code workspaceFile.

{ "Binder": [{ "Away":"vscode"},{ "Away":"vscode-docs"},{ "Away":"vscode-generator-code"}], "Ideas": { "window.zoomLevel":1, "files.autoSave":"after delay"}}

If you switch from a single folder instance to multiple folders, VS Code adds the appropriate editor-wide settings from the first folder to the new global workspace settings.

You can easily review and change the various settings files through the settings editor. The Settings Editor tabs allow you to choose your user settings, global workspace settings, and individual folder settings.

Multi-root workspaces in Visual Studio Code (12)

(Video) How to use Workspaces in Visual Studio Code | Open Multiple Folders and Projects with VSCode

You can also open specific preference files with the commands:

  • Settings: Open user settings- Open your global user settings
  • Settings: Open workspace settings- Open the settings area of ​​your workspace file.
  • Settings: Open folder settings- Open the settings for the active folder.

Global workspace settings override user settings and folder settings can override workspace or user settings.

Unsupported folder settings

Editor-wide folder settings that are not supported appear grayed out in your folder settings and are filtered out of theDEFAULT SETTINGS FOR FOLDERSList. You will also see an information icon in front of the setting.

Multi-root workspaces in Visual Studio Code (13)


For multi-root workspaces, VS Code looks in all folderslaunch.jsondebugs configuration files and displays them with the folder name as a suffix. In addition, VS Code also shows launch configurations defined in the workspace configuration file.

Multi-root workspaces in Visual Studio Code (14)

The example above shows the debugging configurations for theTSLint extension. There is aStartconfiguration from thetslintextension folder to launch the extension running in the VS Code extension host and also aappendconfiguration from thetslint-serverFolder to attach the debugger to a running TSLint server.

The three can also be seenadd configcommands for the folders,tslint,tslint-server, Andtslint-tests, im vscode-tslintWorkplace. Theadd configCommand opens either an existinglaunch.jsonfile in folder.vscodeSubfolder or create a new one and show the Debug Configuration Template drop-down menu.

Multi-root workspaces in Visual Studio Code (15)

variablesused in a configuration (ex${workspaceFolder}or the now obsolete one${workspaceRoot}) are resolved relative to the folder they belong to. It is possible to set one variable per workspace folder by appending the root folder name to a variable (separated by a colon).

Workspace launch configurations

Workspace-related launch configurations live in the"Start"section of the workspace configuration file (Workspaces: Open the workspace configuration filein the command palette):

Multi-root workspaces in Visual Studio Code (16)

Alternatively, new launch configurations can be added via the "Add Config (workspace)" entry of the Launch Configuration drop-down menu:

Multi-root workspaces in Visual Studio Code (17)

A composite launch configuration can reference the individual launch configurations by name as long as the names are unique within the workspace, for example:

 "Links": [{ "Name":"Start Server & Client", "configurations": [ "Start server", "Start client"]}]

If each launch configuration name is not unique, the qualifying folder can be specified using a more verbose "folder" syntax:

(Video) Working with Multiple Projects in VS Code

 "Links": [{ "Name":"Start Server & Client", "configurations": [ "Start server",{ "Binder":"Webclient", "Name":"Start client"},{ "Binder":"Desktop-Client", "Name":"Start client"}]}]

In addition tolinks, DieStartThe workspace configuration file section can also contain regular launch configurations. Make sure that all variables used are explicitly mapped to a specific folder, otherwise they will not be valid for the workspace. For more details on explicitly scoped variables, see thevariable reference.

Here is an example of a launch configuration where the program is in a "Program" folder and all files from a "Library" folder should be skipped when stepping:

"Start": { "configurations": [{ "Typ":"Node", "Inquiry":"Start", "Name":"Start test", "Program":"${workspace folder:program}/test.js", "skipFiles": [ "${workspaceFolder:Library}/out/**/*.js"]}]}


Similar to how VS Code looks for debugging configurations, VS Code also tries to automatically detect tasks from gulp, grunt, npm and TypeScript project files in all folders in a workspace and look for tasks defined inTasks.jsonfiles. The location of tasks is indicated by a folder name suffix. Note that tasks are defined inTasks.jsonmust be version 2.0.0.

Multi-root workspaces in Visual Studio Code (18)

From the TSLint extensionWorkplaceExample above you can see there are twoconfigured tasksout ofTasks.jsonfiles in thetslintAndtslint-testsFolders and numerous auto-detected npm and TypeScript compilersrecognized tasks.

Workspace task configuration

Workspace-related tasks live in the"Tasks"section of the workspace configuration file (Workspaces: Open the workspace configuration filein the command palette). Only"sleeve"And"Procedure"Tasks of type can be defined in the workspace configuration file.

source control

With multi-root workspaces, there is oneSOURCE CONTROL PROVIDERSection that gives you an overview if you have multiple active repositories. These can be contributed by multiple SCM vendors; For example, you can have Git repositories side-by-side with Azure DevOps Server workspaces. If you select repositories in this view, you can see the source control details below.

Multi-root workspaces in Visual Studio Code (19)

You can useCtrl+clickorShift+clickto select multiple repositories. Your details will appear as separate areas below.


If you are an extension author, you can check oursIntroduction of multi-root workspace APIsGuide to learn more about VS Code multi-root workspace APIs and how to make your extension work well in multiple folders.

Below are some of the popular extensions that have adopted the multi-root workspace APIs.

note: If an extension doesn't yet support multiple folders, it will still work in the first folder of your multi-root workspace.

Renewal Recommendations

VS Code supports folder-level extension recommendations through theextensions.jsonfiles under the folder.vscodesubfolders. You can also provide global workspace extension recommendations by adding them to yours.code workspaceFile. You can use the...Extensions: Configure recommended extensions (workspace folder)Command to open your workspace file and add extension IDs ({publisherName}.{extensionName}) to itExtensions.RecommendationsRow.

{ "Binder": [{ "Away":"vscode"},{ "Away":"vscode-docs"}], "extensions": { "Recommendations": ["eg2.tslint","dbaeumer.vscode-eslint","esbenp.prettier-vscode"]}}

Next Steps

  • What is a VS Code "workspace"?- More about single folder and multi-root workspaces.
  • Debugging- Learn how to set up debugging for your application.
  • Tasks- Tasks allow you to run external tools like compilers in VS Code.

Frequently Asked Questions

How can I work with a single project folder again?

You can either close the workspace and open the folder directly, or remove the folder from the workspace.

What do I have to do as an extension author?

See oursIntroduction of multi-root workspace APIsGuide. Most extensions can easily support multi-root workspaces.


(Video) Configuring VS Code Workspaces for Multiple ObjectScript Connections


How do I add another workspace in VS Code? ›

You can start off by opening a folder in VS Code and then later add more folders as you see fit. Unless you already have opened a . code-workspace file, the first time you add a second folder to a workspace, VS Code will automatically create an "untitled" workspace.

How do I change the root directory in Visual Studio Code? ›

Go to File > Preferences > Settings, search for pythonpath. Under the Pylance options you should see Extra Paths, this is where you set your source folder.

What is multi root workspace? ›

Multi-root workspaces let developers group a set of disparate project folders into one workspace, instead of having to work with files and folders residing only in a single root folder.

Can you have multiple projects open in VS Code? ›

You can simply do File>New Window and open the other project in the new window. Because after you close VSCODE and launch it again it opens only one of these two windows. But with workspace you keep both.

Where is root directory in Visual Studio Code? ›

Within your home folder, create a folder called VSCodeProjects. This folder will be the root folder for all your applications developed with Visual Studio Code.

How do I get to root directory in Visual Studio? ›

This is located at C:\Documents and Settings\UserName\My Documents\Visual Studio Projects\.

How do I set the root directory? ›

You can change to the root directory of the current drive with the “cd” command or switch to a root directory on another drive. The root directory is the top-most folder on the drive. For example, “C:\” is the root directory for the C: drive and “D:\” is the root directory for the D: drive.

How do I open multiple projects in VS? ›

To set multiple startup projects
  1. In Solution Explorer, select the solution (the top node).
  2. Choose the solution node's context (right-click) menu and then choose Properties. ...
  3. Expand the Common Properties node, and choose Startup Project.
  4. Choose the Multiple Startup Projects option and set the appropriate actions.
Nov 3, 2022

How do I open two tabs in the same file in Visual Studio? ›

How to open two instances of the same file side by side in Visual Studio 2019:
  1. Open the file.
  2. Click Window → New Window.
  3. A new window should be open with the same file.
  4. Click on Window → New Vertical Document Group.

How do I use multiple git repositories? ›

The usual workflow when working with the code synced to two or more repositories looks like this:
  1. make changes in the code of the project;
  2. use git add command to add changed/updated files as usual;
  3. make a commit using git commit command as usual;
  4. push code changes to the first repository: git push github master ;


1. VS Code tips — Managing multiple git repositories in a workspace
(Code 2020)
2. How To Open Multiple Projects / Folders In VS Code *2022*
(Tech Talk Tutorials)
3. VsCode Tutorial: How to use a workspace to manage multiple projects at the same time.
(Dr. Todd Wolfe Technology Training and Tutorials)
4. Workspaces in VS Code on Windows 10 Explained
5. Master VS Code: Workspaces
(André Casal)
6. How to join two projects into one workspace in Visual Studio Code
(Spring Everyday)
Top Articles
Latest Posts
Article information

Author: Terrell Hackett

Last Updated: 01/14/2023

Views: 5883

Rating: 4.1 / 5 (72 voted)

Reviews: 87% of readers found this page helpful

Author information

Name: Terrell Hackett

Birthday: 1992-03-17

Address: Suite 453 459 Gibson Squares, East Adriane, AK 71925-5692

Phone: +21811810803470

Job: Chief Representative

Hobby: Board games, Rock climbing, Ghost hunting, Origami, Kabaddi, Mushroom hunting, Gaming

Introduction: My name is Terrell Hackett, I am a gleaming, brainy, courageous, helpful, healthy, cooperative, graceful person who loves writing and wants to share my knowledge and understanding with you.