861

For example, Visual Studio Code talks about applying settings at the user level vs the workspace level.

On the one hand,

  • it could refer to a project directory that you have opened; or
  • it could refer to everything you have opened in a particular window.

The page referenced above says

"Workspace: These settings are stored inside your workspace in a .vscode folder and only apply when the workspace is opened."

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Nat Kuhn
  • 9,493
  • 5
  • 18
  • 26
  • 55
    I still feel there is more to this question. I am new to VS Code, but not to coding. I figured a workspace is "merely" the project directory, as the OP suggests. However, if I choose `File --> Open Workspace`, the file explorer dialog box does not allow me to simply "open" a folder, I have to find a specific file. :( – Mike Williamson Jan 17 '18 at 01:45
  • 5
    I'm with you guys. I'm unclear of the difference between a normal folder structure and then a workspace. I've made a workspace with VS Code but don't see any difference except a different file icon. I know workspaces are local copies of different branches but couldn't a standard folder for the separate changes do the same thing? I'd like documentation on this as it is very hard to find. – Daniel Jackson Mar 14 '18 at 15:55
  • 3
    It appears that there may be only one workspace open per window. – Paul Price Aug 27 '18 at 22:27
  • Besides the existing answers, it is worth mentioning that extensions can be enabled or disabled for workspaces (but not for folders). Strangely, I could not find those enablings or disablings in any `settings.json` or `.code-workspace` file mentioned in the answers. – Carsten Führmann Aug 29 '18 at 13:57
  • 4
    I wonder how I create a new empty workspace. It's a bit strange that I can open and save an existing workspace, but not close it to start with an empty one... – rantanplan Jan 22 '19 at 19:51
  • Few more related questions please clarify 1. In Welcome screen there is "Add workspace folder.." option, what is the need to create multiple workspaces instead of multiple folders under single workspace 2. why can't I simply create folder and create new files under it, why workspace is needed ? – vikramvi Feb 13 '19 at 10:19
  • 2
    @rantanplan: There's no need for a blank workspace. That question is at https://stackoverflow.com/questions/53308870/how-to-create-a-workspace. When you use Open Folder you essentially have a workspace that VSCode handles without saving. – aamarks May 30 '19 at 16:48
  • 1
    Probably what most confused people here want is the "Project Manager" plugin for VS Code. https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager (It's more like projects in Atom, but including a nice UI, focused on single-folder projects, easy to pick them using a project open palette) – trusktr Jun 10 '19 at 19:16
  • One use case for .code-workspaces, is that they can be [duplicated](https://code.visualstudio.com/updates/v1_24#_duplicate-workspace-in-new-window). This is the closest workaround VS-Code has for multi-screening a single folder project. – PeterN Mar 08 '21 at 13:01

17 Answers17

549

What is a workspace?

A project that consists of one or more root folders, along with all of the Visual Studio Code configurations that belong to that project. These configurations include:

Why is a workspace so confusing?

Visual Studio Code does not use the term consistently across the UI (I've opened a GitHub issue to address this). Sometimes it refers to a workspace as described above, and other times it refers to a workspace as a project that is specifically associated with a .code-workspace file.

A good example being the recent files widget. Notice in the linked screenshot that all projects are grouped under the same "workspaces" heading, which would indicate that everything there is a workspace. But then projects with a .code-workspace file are given a "Workspace" suffix, contradicting the heading and indicating that only those files are actually workspaces.

What is a .code-workspace file?

It is a JSON file with comments that stores all of the configuration data mentioned above, in addition to the location of all root folders belonging to a workspace.

Do I need a .code-workspace file?

Only if you're creating a multi-root workspace, in which case you'll have a single .code-workspace file that automatically restores all of the workspace settings, in addition to all of the root folders that you want to be displayed in the Explorer.

What about single folder projects?

Everything is automated.

When you open a folder in Visual Studio Code and start making modifications to the editor that are specifically related to the project you're currently working on, Visual Studio Code automatically creates a .vscode folder and stores it in the root of the project folder that you're working on. This .vscode folder has files that store the changes you made.

For example, if you change Visual Studio Code settings that you want to apply only to your current project, Visual Studio Code creates a settings.json file with those updates, and that file is stored in the .vscode folder.

You can create a .code-workspace file that includes just a single root folder if you really want to. You'd then be able to either open the project folder directly, or open the workspace file. But I can't think of any reason why this would be beneficial.

How do I create a .code-workspace file?

Go to menu File → Save Workspace As...

How do I add root folders to a workspace?

Go to menu File → Add Folder to Workspace....

How do I open a workspace that is defined by a .code-workspace file?

Go to menu File → Open Workspace....

Alternatively, double click the .code-workspace file. Visual Studio Code won't open the actual file. Instead, it will read that file and open the folders that belong to that workspace.

How do I view the actual .code-workspace file?

Go to menu File → Open... and select the target .code-workspace file.

Alternatively, open the workspace associated with that file. Then open the command palette, search for, and select the Workspaces: Open Workspace Configuration File command.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
jabacchetta
  • 45,013
  • 9
  • 63
  • 75
  • I think comment here is the best place. This let me cleared a bit things in myself after I realized an issue I had about choosing right Python interpreter( https://stackoverflow.com/questions/54106071/how-to-setup-virtual-environment-for-python-in-vs-code/57407774#57407774), but now I have vs code complaining saying that in launch.json the "args" proprety is not allowed,those file was produced automatically, and I can't find a syllabus for that object – Carmine Tambascia Aug 08 '19 at 08:34
  • 1
    When saving a 'Workspace' in Linux do not forget to add the .code-workspace extension to the name of the Workspace. e.g [ myworkspace.code-workspace ] I kept having to re-create the workspace as 'open' could not see any workspace files. (maybe something to recommend/pull request to auto-populate if no extension is set on Save...) – JI-Web Nov 13 '19 at 00:49
  • 4
    One reason you might create a `.code-workspace` file for a single root folder is that there are certain settings (e.g. `files.associations`) which VSCode will not honor in a `.vscode/settings.json`, but will honor in an explicit workspace. – Carl Meyer Mar 19 '20 at 23:44
  • Trying not to add confusion but it does seem for a single folder there is a "virtual" workspace because debug variables like this work "${workspaceFolder}/app" – Atherion Aug 08 '20 at 16:34
  • 1
    Is it possible to use the same configs for all files I open using VS Code? I am a casual Python coder and I would like the default for Python interpreter as the anaconda base environment. – Black Jack 21 Sep 26 '20 at 15:46
  • This gave me a good laugh this morning, as the very first sentence links the vscode "root folders" to the wikipedia "root directory" which are certainly not the same thing at all. – batpox Oct 14 '20 at 11:57
  • @batpox That's the thing. There is no concept of a project in VS Code. Only *root* folders in a completely generic sense. – Ate Somebits Mar 04 '21 at 10:43
  • There is another option to view the **current file** in `vscode`: in the `command palette` (f1): `preferences: Open Workspace settings (json)` – Timo Apr 27 '21 at 18:19
  • Have you also noticed how, when in multi-root workspace, you configure something that is root-folder dependent, the prompt is to "select workspace", i.e. `Configure Tests` or similar. (*whereas in UI-mode settings config, these are called "folders"*). That's a dead giveaway they haven't given this concept proper thought. – Ate Somebits Jul 19 '21 at 11:04
  • I just want to open the workspace config file from VScode and the last sentence helped: `open the command palette, search for, and select the Workspaces: Open Workspace Configuration File`. See also [my comment](https://stackoverflow.com/questions/44629890/what-is-a-workspace-in-visual-studio-code#comment118937111_57134632). – Timo Apr 03 '22 at 19:35
  • What's missing from this otherwise excellent answer is why a dev would/should choose to use a workspace. What are the use cases, when should a dev work with folders and when with workspaces? – Keith Bluestone Jun 22 '22 at 12:12
  • One more reason for me to use .code-workspace files for single-folder projects is to store different window configurations for the same folder in different .code-workspace files. – I. Amon Aug 21 '22 at 10:34
161

You can save settings at the workspace level and you can open multiple folders in a workspace. If you want to do either of those things, use a workspace, otherwise, just open a folder.

A Visual Studio Code workspace is a list of a project's folders and files. A workspace can contain multiple folders. You can customize the settings and preferences of a workspace.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Jody Bleyle
  • 1,756
  • 2
  • 11
  • 12
  • 2
    I'm new to VS Code, but I can't see a way to open one workspace per project. If I open a new file and try to save a new workspace, I move the existing workspace file instead. So I don't think it's correct that workspace == project. – Åsmund Mar 25 '18 at 14:51
  • 11
    "You can save settings at the workspace level and you can open multiple folders in a workspace. If you want to do either of those things, use a workspace." Technically you don't need a workspace to save settings on a folder level. That can just be done with a `settings.json` within a .vscode folder in the relevant folder. However if you want multiple folders in a workspace, and settings that apply to all, then you have to use a workspace. – Gandalf Saxe Jul 22 '18 at 15:49
  • 4
    Sounds a bit like a solution in Visual Studio to me – Alexander Derck Oct 24 '18 at 19:50
  • You don't create a new workspace until you need one. You simply use Open Folder on your project folder and start working on a file. Until you have a reason to make that a workspace you don't have to save it. If you had a Workspace open and you switch back to it the files that were open are open again. If you leave the workspace and go back to new project folder without a workspace the files you had open in that are open again. A good reason for saving as Workspace is to include other folders. – aamarks May 29 '19 at 05:54
  • 3
    Workspaces are INCREDIBLY confusing in Visual Studio Code. Straight up. I really don't understand why the creators of VSC didn't just go with the paradigm of projects. –  Jun 10 '19 at 15:41
  • this is best answer! – Jetwiz Apr 11 '21 at 18:33
108

A workspace is just a text file with a (.code-workspace) extension. You can look at it by opening it with a text editor. I too was frustrated by the idea of a workspace and how it is implemented in Visual Studio Code. I found a method that suits me.

Start with a single "project" folder.

Open Visual Studio Code and close any open workspaces or files or folders. You should see only "OPEN EDITORS" and "NO FOLDER OPENED" in the EXPLORER.

From the menu bar → File → Open Folder.... Navigate to where you want to put your folder and right click to open a new folder. Name it whatever you want, then click on "Select Folder". It will appear in the *Visual Studio Code explorer.

Now from menu File → Save Workspace As.... Name the workspace and save it wherever you want to keep all your workspaces, (not necessarily where your project folders are). I put all mine in a folder called "Visual Studio Code workspace".

It will be saved as a (.code-workspace) file and is just an index to all the files and folders it contains (or points to) wherever they may be on your hard drive. You can look at it by opening it with a text editor. Close the folder you created and close Visual Studio Code.

Now find your workspace "file" and double click on it. This will open Visual Studio Code with the folder you created in your workspace. Or you can open Visual Studio Code and use "Open Workspace".

Any folders you create from within your Visual Studio Code workspace will be inside your first folder. If you want to add any more top level folders, create them first wherever you want them and then use "Add To Workspace.." from Visual Studio Code.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Robert Schindehette
  • 1,081
  • 1
  • 7
  • 5
  • I'm still not sure that this is the "best" or "proper" method that MS intended to be used, but a) that should be documented and b) you should join Mensa for having been able to figure out something that works and seems as logical as possible. I moved to VS Code from PHPStorm due to the latter's immense size, but for an IDE that is so lightweight and seemingly-awesome at first glance, I am now absolutely bewildered by this incredible UX nightmare! Anyway TYVM for the suggestion and apologies for the rant :-) – Kenny83 Nov 22 '18 at 21:23
  • Wait, so are you saying that the workspace *file* does not need to be in the same folder as the (presumably) associated *project folder*? Is that considered a good practice? I'm imagining that, for instance, a workspace file could be created that is shared by all engineers working on the same project (to allow for shared styling, etc.), then user settings can override that individually as they wish. For this to be viable, it seems the workspace file should be in the same project folder, right? I guess I have 2 questions: (1) What's feasible/allowed?, and (2) What's best practice? – Mike Williamson Feb 03 '19 at 19:16
  • This will cause problems for people working on multiple projects at a time. – Shahir Ansari Mar 04 '20 at 11:54
88

The title and subsequent question in the OP seem to boil down to:

  1. What is a workspace in Visual Studio Code?
  2. How do workspace settings work?

Short answer:

A workspace is a virtual collection of folders opened simultaneously in Visual Studio Code and defined in a .code-workspace file. Opening this file will open the collection of folders automatically. This is called a "multi-root" workspace.

The .code-workspace file also defines workspace settings that are used by the instance of Visual Studio Code where the workspace is opened.

When a workspace is not defined, i.e. you open a folder on its own, you can create "workspace settings" that are saved in a .vscode\settings.json file in the root of that folder structure.

In more detail:

Visual Studio Code uses the word "workspace" a little ambiguously in places. The first use to consider is in what is calls a multi-root workspace.

A multi-root workspace is a set of folders (the "roots") that are opened collectively in an instance of Visual Studio Code. There is no need for these folders to share parent folders; indeed that is the point since Visual Studio Code normally uses a single folder in the Explorer side-bar.

A multi-root workspace is defined by a .code-workspace (JSON) file which contains both the list of folders to be included in the workspace and Visual Studio Code settings.

Regarding those workspace settings...

When you open menu File → Preferences → Settings the settings editor is shown. At the very least you should see a USER SETTINGS tab. These are the Visual Studio Code settings that are universal for your user account on your local machine. In Windows these are saved in %APPDATA%\Code\User\settings.json.

Individual folders (often each of the "root" folders in a workspace) might have a .vscode folder with their own settings.json file. When opened individually, i.e. not as part of a workspace, the content of these settings.json files is presented under the WORKSPACE SETTINGS tab, and all the settings in that file are used by the running Visual Studio Code instance.

When opening a multi-root workspace things behave differently. Firstly, the WORKSPACE SETTINGS tab shows the options set in the .code-workspace file. Secondly, any folder with a settings.json file will appear under a new FOLDER SETTINGS tab. Be aware that, when in a multi-root workspace, only a limited number of settings from each folder's settings.json are used. I suggest you open the link above to read further.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Charlie Joynt
  • 4,411
  • 1
  • 24
  • 46
  • Is there any documentation specifying location of `settings.json` to be other than `%APPDATA%\Code\User`? In my case, when I place this file into a folder, some settings are not applied as they are when the file is in the "default" location in `%APPDATA%`. – Danijel Dec 10 '18 at 12:54
  • 1
    As far as I can see, no. The documentation described the "default" location for Windows as `%APPDATA%\Code\User`. I haven't noticed anything that suggests the `%APPDATA%` location itself is used at all. https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations – Charlie Joynt Dec 17 '18 at 13:39
  • 1
    There is another question here on SO about _changing_ the location of the user settings location, and one answer suggests that you need to override the default location with a command-line parameter: https://stackoverflow.com/questions/44575312/change-vscode-user-settings-location/44575963 – Charlie Joynt Dec 17 '18 at 13:40
  • Charlie, if there is no documentation, what do you base your answer on? Source code? – Danijel Dec 17 '18 at 13:44
  • My answer is based on available documentation and end-user experience. I see no documentation _about being able to specify the (default) location of the user configuration file_; in other words, I can't find anything that suggests `%APPDATA%` itself is a valid location. It sounds like your testing indicates that files in that folder do work? – Charlie Joynt Dec 17 '18 at 14:31
40

The main utility of a workspace (and maybe the only one) is to allow to add multiple independent folders that compounds a project. For example:

- WorkspaceProjectX  
-- ApiFolder   (maybe /usr/share/www/api)  
-- DocsFolder  (maybe /home/user/projx/html/docs)  
-- WebFolder   (maybe /usr/share/www/web)

So you can group those in a workspace for a specific project instead of have to open multiple folders windows.

You can learn more here.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
sdlins
  • 2,195
  • 1
  • 23
  • 31
  • 2
    This is a great distinction. I already use single-folder workspaces with multiple projects by opening a folder with the .sln file that references subdirectories with the included projects. But they are all related with a dependency hierarchy that is maintained by the solution. A multi-root workspace would not have such a relationship. – melston Sep 21 '19 at 18:37
  • 7
    This is the best answer as it addresses the "why" a workspace would be used. You can find all sorts of technical definitions around the mechanics of a workspace but it was difficult to understand why I would want to use it. The workspace is similar to a "solution" in Visual Studio Professional. – FrankO Mar 01 '20 at 21:29
  • I see people casually referring to workspaces as if they represent a project, but that doesn't seem to bear out. Everyone that has ever asked "how do you have multiple projects at once accessible in your sidebar?" is always told "vscode let's you do that now, just use Add Folder to Workspace". It seems more likely that a workspace is intended for grouping "all projects you're likely to use together". What I want to know is, why not put *all* projects you are working on in your workspace? vscode correctly handles different folders having different source control, build/make tasks etc. – thomasrutter Dec 02 '20 at 06:06
11

On some investigation, the answer appears to be (a).

When I go to change the settings, the settings file goes into a .vscode directory in my project directory.

Nat Kuhn
  • 9,493
  • 5
  • 18
  • 26
  • 3
    It's not just 1 folder though. You can configure a workspace to contain multiple directories. What I was wondering is what the difference is between a workbench and a workspace. – Marses Feb 07 '18 at 11:40
10

I just installed Visual Studio Code v1.25.1. on a Windows 7 Professional SP1 machine. I wanted to understand workspaces in detail, so I spent a few hours figuring out how they work in this version of Visual Studio Code. I thought the results of my research might be of interest to the community.

First, workspaces are referred to by Microsoft in the Visual Studio Code documentation as "multi-root workspaces." In plain English that means "a multi-folder (A.K.A "root") work environment." A Visual Studio Code workspace is simply a collection of folders - any collection you desire, in any order you wish. The typical collection of folders constitutes a software development project. However, a folder collection could be used for anything else for which software code is being developed.

The mechanics behind how Visual Studio Code handles workspaces is a bit complicated. I think the quickest way to convey what I learned is by giving you a set of instructions that you can use to see how workspaces work on your computer. I am assuming that you are starting with a fresh install of Visual Studio Code v1.25.1. If you are using a production version of Visual Studio Code I don't recommend that you follow my instructions because you may lose some or all of your existing Visual Studio Code configuration! If you already have a test version of Visual Studio Code v1.25.1 installed, **and you are willing to lose any configuration that already exists, the following must be done to revert your Visual Studio Code to a fresh installation state:

Delete the following folder (if it exists):

  C:\Users\%username%\AppData\Roaming\Code\Workspaces (where "%username%" is the name of the currently logged-on user)

You will be adding folders to Visual Studio Code to create a new workspace. If any of the folders you intend to use to create this new workspace have previously been used with Visual Studio Code, please delete the ".vscode" subfolder (if it exists) within each of the folders that will be used to create the new workspace.

Launch Visual Studio Code. If the Welcome page is displayed, close it. Do the same for the Panel (a horizontal pane) if it is displayed. If you received a message that Git isn't installed click "Remind me later." If displayed, also close the "Untitled" code page that was launched as the default code page. If the Explorer pane is not displayed click "View" on the main menu then click "Explorer" to display the Explorer pane. Inside the Explorer pane you should see three (3) View headers - Open Editors, No Folder Opened, and Outline (located at the very bottom of the Explorer pane). Make sure that, at a minimum, the open editors and no folder opened view headers are displayed.

Visual Studio Code displays a button that reads "Open Folder." Click this button and select a folder of your choice. Visual Studio Code will refresh and the name of your selected folder will have replaced the "No Folder Opened" View name. Any folders and files that exist within your selected folder will be displayed beneath the View name.

Now open the Visual Studio Code Preferences Settings file. There are many ways to do this. I'll use the easiest to remember which is menu File → Preferences → Settings. The Settings file is displayed in two columns. The left column is a read-only listing of the default values for every Visual Studio Code feature. The right column is used to list the three (3) types of user settings. At this point in your test only two user settings will be listed - User Settings and Workspace Settings. The User Settings is displayed by default. This displays the contents of your User Settings .json file. To find out where this file is located, simply hover your mouse over the "User Settings" listing that appears under the OPEN EDITORS View in Explorer. This listing in the OPEN EDITORS View is automatically selected when the "User Settings" option in the right column is selected. The path should be:

C:\Users\%username%\AppData\Roaming\Code\User\settings.json

This settings.json file is where the User Settings for Visual Studio Code are stored.

Now click the Workspace Settings option in the right column of the Preferences listing. When you do this, a subfolder named ".vscode" is automatically created in the folder you added to Explore a few steps ago. Look at the listing of your folder in Explorer to confirm that the .vscode subfolder has been added. Inside the new .vscode subfolder is another settings.json file. This file contains the workspace settings for the folder you added to Explorer a few steps ago.

At this point you have a single folder whose User Settings are stored at:

C:\Users\%username%\AppData\Roaming\Code\User\settings.json

and whose Workspace Settings are stored at:

C:\TheLocationOfYourFolder\settings.json

This is the configuration when a single folder is added to a new installation of Visual Studio Code. Things get messy when we add a second (or greater) folder. That's because we are changing Visual Studio Code's User Settings and Workspace Settings to accommodate multiple folders. In a single-folder environment only two settings.json files are needed as listed above. But in a multi-folder environment a .vscode subfolder is created in each folder added to Explorer and a new file, "workspaces.json," is created to manage the multi-folder environment. The new "workspaces.json" file is created at:

c:\Users\%username%\AppData\Roaming\Code\Workspaces\%workspace_id%\workspaces.json

The "%workspaces_id%" is a folder with a unique all-number name.

In the Preferences right column there now appears three user setting options - User Settings, Workspace Settings, and Folder Settings. The function of User Settings remains the same as for a single-folder environment. However, the settings file behind the Workspace Settings has been changed from the settings.json file in the single folder's .vscode subfolder to the workspaces.json file located at the workspaces.json file path shown above. The settings.json file located in each folder's .vscode subfolder is now controlled by a third user setting, Folder Options. This is a drop-down selection list that allows for the management of each folder's settings.json file located in each folder's .vscode subfolder. Please note: the .vscode subfolder will not be created in newly-added explorer folders until the newly-added folder has been selected at least once in the folder options user setting.

Notice that the Explorer single folder name has bee changed to "UNTITLED (WORKSPACE)." This indicates the following:

  1. A multi-folder workspace has been created with the name "UNTITLED (WORKSPACE)
  2. The workspace is named "UNTITLED (WORKSPACE)" to communicate that the workspace has not yet been saved as a separate, unique, workspace file
  3. The UNTITLED (WORKSPACE) workspace can have folders added to it and removed from it but it will function as the ONLY workspace environment for Visual Studio Code

The full functionality of Visual Studio Code workspaces is only realized when a workspace is saved as a file that can be reloaded as needed. This provides the capability to create unique multi-folder workspaces (e.g., projects) and save them as files for later use! To do this select menu File → Save Workspace As from the main menu and save the current workspace configuration as a unique workspace file. If you need to create a workspace "from scratch," first save your current workspace configuration (if needed) then right-click each Explorer folder name and click "Remove Folder from Workspace." When all folders have been removed from the workspace, add the folders you require for your new workspace. When you finish adding new folders, simply save the new workspace as a new workspace file.

An important note - Visual Studio Code doesn't "revert" to single-folder mode when only one folder remains in Explorer or when all folders have been removed from Explorer when creating a new workspace "from scratch." The multi-folder workspace configuration that utilizes three user preferences remains in effect. This means that unless you follow the instructions at the beginning of this post, Visual Studio Code can never be returned to a single-folder mode of operation - it will always remain in multi-folder workspace mode.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Bill Vallance
  • 471
  • 3
  • 19
  • For me the .vscode folder didn't get created until I made a change to one of the Workplace Settings, but otherwise this writeup was definitely helpful in giving me a better understanding of how it all works. – James Toomey Mar 20 '19 at 00:49
8

Short Answer:

Use a folder instead of single-folder workspace.

Only use multi-root Workspaces if needed. You need multi-root workspaces when you need to work with multiple project folders. This can be very helpful when you are working on several related projects at one time. For example, you might have a repository with a product's documentation which you like to keep current when you update the product source code.

Why "Only use multi-root workspaces if needed"?

There is only basically two differences between single-folder workspace and a folder:

  1. you open a single-folder workspace by File > Open Workspace from File... and then select a <name>.code-workspace file. You open a folder by File > Open Folder... and then select a folder.

  2. When you open a single-folder workspace using <name>.code-workspace file, all project specific settings will be added into the <name>.code-workspace file. When you open a project using folder, all project specific settings will be saved in .vscode/settings.json file.

Even if you take the time to create a <name>.code-workspace file for a single-folder workspace, you can open that by File > Open Folder.... Depending on your access method, sometimes the settings can be in .vscode/settings.json file or <name>.code-workspace file. Better use a consistent method to access your project folders. Moreover, launch configurations (.vscode/launch.json) are saved beside Folder Settings (.vscode/settings.json) and not Workspace Settings (<name>.code-workspace). Most of the time, you will need the .vscode directory anyway.

Long Answer:

The documentation says:

The concept of a workspace enables VS Code to:

  • Configure settings that only apply to a specific folder or folders but not others.
  • Persist task and debugger launch configurations that are only valid in the context of that workspace.
  • Store and restore UI state associated with that workspace (for example, the files that are opened).
  • Selectively enable or disable extensions only for that workspace.

In another place, it says:

Configurations can be overridden at multiple levels by the different setting scopes:

  • User settings - Apply globally to all VS Code instances.
  • Workspace setting - Apply to the open folder or workspace and override User settings.
  • Workspace Folder settings - Apply to a specific folder of a multi-root workspace. Override User and Workspace settings.

So, there is basically three types of settings:

  • Folder settings (highest precedence)
  • Workspace settings
  • User settings (lowest precedence)

You can modify folder settings by assigning a keybinding to Preferences: Open Folder Settings and then using the keybinding.

You can modify workspace settings by Ctrl + Shift + P → Preference: Open Workspace Settings.

You can modify user settings by File > Preferences > Settings.

Your workspace settings will be added into the <name>.code-workspace file.

Your folder settings will be saved in the .vscode/settings.json file.

There is Confusion

Evidence 1:

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

Evidence 2:

A VS Code "workspace" is usually just your project root folder. Workspace settings as well as debugging and task configurations are stored at the root in a .vscode folder.

Evidence 3:

The visual difference of having a folder opened versus opening a .code-workspace file can be subtle. To give you a hint that a .code-workspace file has been opened, some areas of the user interface (for example, the root of the File Explorer) show an extra (Workspace) suffix next to the name.

Where is the Confusion?

The devil is in the details (documentation and implementation).

Documentation

In the documentation, they said different things is different places. There is no consistency.

In one place they say:

VS Code provides two different scopes for settings:

  • User Settings - Settings that apply globally to any instance of VS Code you open.
  • Workspace Settings - Settings stored inside your workspace and only apply when the workspace is opened.

In another place they say:

Configurations can be overridden at multiple levels by the different setting scopes:

  • User settings - Apply globally to all VS Code instances.
  • Workspace setting - Apply to the open folder or workspace and override User settings.
  • Workspace Folder settings - Apply to a specific folder of a multi-root workspace. Override User and Workspace settings.

So, basically they did not consistently say that there are three levels of settings. Specially look at the title of their documentation for settings. It is titled User and Workspace Settings (notice how the Folder settings is missing from the title). It mentions Workspace Folder settings only once when they are talking about settings precedence.

Implementation

The documentation says:

Workspace settings enable you to configure settings in the context of the workspace you have opened 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 you opened a .code-workspace file.

So, basically, when there isn’t any workspace (for example, you did not open the project using <name>.code-workspace) and you Ctrl + Shift + P → Preference: Open Workspace Settings, it opens the .vscode/settings.json file (which is actually for folder settings and not workspace settings, though the name explicitly says Open Workspace Settings).

You might have already noticed in the Long Answer: that "they" did not keep any easy way to directly access folder settings (you have to assigning a keybinding to the Preferences: Open Folder Settings command and then use the keybinding. You can not even access this "Command" from the Command Pallet using Ctrl + Shift + P directly).

Moreover, you have to modify folder settings using Preference: Open Workspace Settings (note that you are modifying "Folder settings" using "Open Workspace Settings"). Whether Preference: Open Workspace Settings will modify folder settings or workspace settings depends on how you access the project (using File > Open Folder... or the <name>.code-workspace file).

They made a simple thing hard by trying to oversimplify it.

Ahmad Ismail
  • 11,636
  • 6
  • 52
  • 87
  • I'm glad I'm not the only one frustrated by VSCode's "workspace" implementation and documentation. More confusing is if you use folders, and not workspaces...and you want extensions enabled/disabled per project folder...where is the settings file that stipulates these extension states? Not in the /.vscode/settings.json file. So I have to enable/disable every extension for every different project manually, instead of being able to copy a file. – Doomd Jan 03 '22 at 17:59
  • Please check https://stackoverflow.com/a/75391857/1772898 and also https://code.visualstudio.com/docs/editor/profiles – Ahmad Ismail Aug 08 '23 at 00:40
3

As of May 2018, it seems that a workspace in Visual Studio Code allows you to have quick access to different but related projects. All without having to open a different folder.

And you can have multiple workspaces too. See references here and you will get the full picture of it:

Reference 1
Reference 2

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
jet2016
  • 345
  • 1
  • 3
  • 11
  • That first link explains it really well, in particularly this quote: `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. This provides a variety of advantages and use cases, such as working on multiple projects at the same time -- say a project's documentation and its source code repositories -- and keeping everything in sync.` – thomasrutter Dec 02 '20 at 06:17
3

They call it a multi-root workspace, and with that you can do debugging easily because:

"With multi-root workspaces, Visual Studio Code searches across all folders for launch.json debug configuration files and displays them with the folder name as a suffix."

Say you have a server and a client folder inside your application folder. If you want to debug them together, without a workspace you have to start two Visual Studio Code instances, one for server, one for client and you need to switch back and forth.

But right now (1.24) you can't add a single file to a workspace, only folders, which is a little bit inconvenient.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Qiulang
  • 10,295
  • 11
  • 80
  • 129
1

Although the question is asking "what is a workspace?", I feel that the source of confusion is the expectation that workspaces should behave more like "projects" in other editors.

So, I to help all the people landing here because of this confusion, I wanted to post the following plugin for Visual Studio Code (not mine), Project Manager.

It has a nice UI for managing (saving and opening) single-folder projects:

Save Projects:

Enter image description here

Open projects with the palette:

Enter image description here

See the current project in the status bar (click to open project palette):

Enter image description here

Access projects in the sidebar:

Enter image description here

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
trusktr
  • 44,284
  • 53
  • 191
  • 263
1
  1. Open the File menu and select Save Workspace As. That will save the current explorer status.
  2. After that you can chose menu File* → Open Workspace to open the before-saved workspace.
Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
lucifer
  • 31
  • 3
1

Just added in February 2021 is this documentation on "What is a VS Code 'workspace'": workspaces.

A Visual Studio Code "workspace" is the collection of one or more folders that are opened in a VS Code window (instance). In most cases, you will have a single folder opened as the workspace but, depending on your development workflow, you can include more than one folder, using an advanced configuration called Multi-root workspaces.

The concept of a workspace enables VS Code to:

Configure settings that only apply to a specific folder or folders but not others. Persist task and debugger launch configurations that are only valid in the context of that workspace. Store and restore UI state associated with that workspace (for example, the files that are opened). Selectively enable or disable extensions only for that workspace. You may see the terms "folder" and "workspace" used interchangeably in VS Code documentation, issues, and community discussions. Think of a workspace as the root of a project that has extra 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 platform's File menu, you will not be inside a workspace. In this mode, some of VS Code's capabilities are reduced but you can still open text files and edit them.

Single-folder workspaces

You don't have to do anything for a folder to become a VS Code workspace other than open the folder with VS Code. Once a folder has been opened, VS Code will automatically keep track of things such as your open files and editor layout so the editor will be as you left it when you reopen that folder. You can also add other folder-specific configurations such as workspace-specific settings (versus global user settings) and task definition and debugging launch files (see below in the workspace settings section).

Multi-root workspaces

Multi-root workspaces are an advanced capability of VS Code that allow you to configure multiple distinct folders to be part of the workspace. Instead of opening a folder as workspace, you will open a .code-workspace JSON file that lists the folders of the workspace. For example:

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

multi-root workspace folders

A multi-root workspace opened in VS Code

  • Note: The visual difference of having a folder opened versus opening a .code-workspace file can be subtle. To give you a hint that a .code-workspace file has been opened, some areas of the user interface (for example, the root of the File Explorer) show an extra (Workspace) suffix next to the name.

And much more at the first link.

Mark
  • 143,421
  • 24
  • 428
  • 436
0

If the Visual Studio Code is a fresh installation;

  1. Click on extensions, search for "python" and click on Install

  2. Click on menu View → Explorer If there in no folder added a folder to the Workspace (menu File → Add folder to Workspace)

  3. If you want to use a virtual Python environment, click on menu File → Preference → Settings

Click on "{} open settings JSON" which is in top right corner of the window, and then add the path to python.exe file which is in the virtual environment:

{
    "python.pythonPath": "C:\\PathTo\\VirtualENV\\python.exe"
}
  1. Start a new terminal and check the correct Python interpreter is selected
Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Klllmmm
  • 126
  • 1
  • 11
-1

This is a must read to understand workspaces.

As many have pointed out, multi-root workspaces are where the Visual Studio Code workspace concept becomes relevant.

But why is another question.

So here is an excerpt from the Eclipse IDE user guide, which got the workspace concept right, amongst other things (totally different to Visual Studio Code, and if you need Visual Studio Code, you shouldn't switch to Eclipse - but you can read the documentation because they explain it right):

Considerations for Git Repositories to be used in Eclipse

The short story

When setting up Git Repositories with EGit, there are two recommendations for the creation of "productive" (as opposed to "playground") Repositories:

  • Don't create the Repository within the Eclipse workspace.
    • Be careful when cloning or creating a Repository.
    • Make sure to use the Git Sharing Wizard correctly.
  • Don't create a Repository with an Eclipse project as root.
    • Make sure to use the Git Sharing Wizard correctly.

The first mistake happens when you specify a workspace folder during cloning or creation of a Repository.

Both mistakes will happen when you use the Git Sharing Wizard from an Eclipse project that you have created manually in your workspace without taking precautions (the wizard has been fixed in the latest version).

Below you will find some motivation for these recommendations.

The longer story

Eclipse Workspace and Repository working directory Git Repositories can be created in different ways, for example by cloning from an existing Repository, by creating one from scratch, or by using the EGit Sharing wizard.

In any case (unless you create a "bare" Repository, but that's not discussed here), the new Repository is essentially a folder on the local hard disk which contains the "working directory" and the metadata folder. The metadata folder is a dedicated child folder named ".git" and often referred to as ".git-folder". It contains the actual repository (i.e. the Commits, the References, the logs and such).

The metadata folder is totally transparent to the Git client, while the working directory is used to expose the currently checked out Repository content as files for tools and editors.

Typically, if these files are to be used in Eclipse, they must be imported into the Eclipse workspace in one way or another. In order to do so, the easiest way would be to check in .project files from which the "Import Existing Projects" wizard can create the projects easily. [...]

Implication

The above has the following implications:

It is probably not a good idea to make a project the root folder of your Repository. The reason is that you will never be able to add another project to this Repository, as the .project file will occupy the root folder; you could still add projects as sub-folders, but this kind of project nesting is known to cause lots of problems all over the place. In order to add another project, you would have to move the project to a sub-folder in the Repository and add the second project as another sub-folder before you could commit this change.

It is a good idea to keep your Repository outside of your Eclipse Workspace. There are several reasons for this:

The new Repository will consider the complete folder structure of the Eclipse workspace as (potential) content. This can result in performance issues, for example when calculating the changes before committing (which will scan the complete .metadata folder, for example); more often than not, the workspace will contain dead folders (e.g. deleted projects) which semantically are not relevant for EGit but cannot be excluded easily.

The metadata (.git-) folder will be a child of the Eclipse Workspace. It is unclear whether this might cause unwanted folder traversals by Eclipse.

You can easily destroy your Repository by destroying your Eclipse Workspace.

This being said, Visual Studio also got it right; why Microsoft decided to disregard the Solutions (.sln) and Project (.vcxproj) concepts in Visual Studio Code is rather intriguing.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Ate Somebits
  • 287
  • 1
  • 18
-2

Simple answer: actually it's like a new buffer in the Vim editor

Do you ever have to built a new directory and open a new Visual Studio Code window for a test project or for a feature that you want to add to your main project? Ok, so you need a workspace and enough CPU high usage...

I just wanted to mention a common usage of workspaces in Visual Studio Code in addition to all other answers.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
TechDogLover OR kiaNasirzadeh
  • 4,566
  • 27
  • 33
-2

A workspace, in my opinion, something that everyone forgot to mention, is a way to create an area with all tools you need to address a single language, like other said, in one project you might have PHP, Python, JavaScript, Node.js, etc.

Creating a workspace for each specific language, you can have all tools for managing, debugging, testing, for example all your JavaScript.

This is much easier to manage, so you can have a workspace for PHP, another for Node.js, ... and one project that have folders in multiple workspaces.

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
FePerrella
  • 1
  • 1