VS Code Folder vs Workspace: What Is the Difference?

The VS Code folder vs workspace difference is scope: a folder is a directory on disk, while a workspace is the collection of one or more folders open in a VS Code window, together with workspace-specific settings and saved editor state.

Opening one folder is already a single-folder workspace. You only need a .code-workspace file when you want to save a workspace configuration, especially one containing multiple root folders.

How a single-folder workspace works

Open a folder with File > Open Folder. VS Code treats it as a workspace automatically. You can configure settings, tasks, and debugging without any extra file.

Workspace settings live in .vscode/settings.json at the folder root. Commit only settings that are safe and useful for everyone on the project.

VS Code also remembers state such as open files and editor layout. Reopening the folder restores that workspace state without requiring a workspace file.

How a saved workspace works

A saved workspace is a .code-workspace JSON file. It lists folders plus optional workspace settings, extension recommendations, tasks, and launch configurations.

Minimal example:

json

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

Open it with File > Open Workspace. Both folders appear as root entries in the File Explorer, and the workspace file name appears there. In File > Open Recent, saved workspaces have a (Workspace) suffix that distinguishes them from folders.

Workspace files support relative paths, which makes them portable when teammates keep the same relative folder layout. Folders elsewhere on disk may require absolute paths.

Choose the right workspace type

Use a simple folder for single projects and self-contained directories. Commit the .vscode folder to share settings with your team. This covers most day-to-day development.

Use a workspace file for multiple related projects. You can also create separate workspace files that expose different folder views or workspace-wide configurations for the same codebase.

Save or discard an untitled workspace

Adding a second folder creates an untitled workspace. It remains available while that VS Code instance is open. When you completely close the instance, VS Code asks whether to save the workspace if you want to reopen it later.

Use File > Save Workspace As to create a permanent .code-workspace file. If you close the untitled workspace without saving, VS Code asks whether to save it before deletion.

Saving a workspace does not delete the existing .vscode folder. In a multi-root workspace, applicable settings there remain folder-specific, while global workspace settings are stored in the .code-workspace file.

To work with multiple folders at once, see how to create and use a multi-root workspace.

Workspace Trust

Both folders and workspace files use the same Workspace Trust boundary. When VS Code asks whether you trust unfamiliar code, leave it in Restricted Mode until you have inspected the authors and contents.

Restricted Mode disables or limits features that can execute code, including tasks, debugging, the terminal, workspace settings, AI agents, and some extensions. Trust the workspace only after reviewing its files and authors.