How VS Code Settings Layering Works: A Team-Shared settings.json Guide

If your team keeps arguing about tabs versus spaces or one developer's editor hides files another sees, the fix is usually not a style guide document — it is understanding how Visual Studio Code layers its settings and committing the right file to the repository. The short answer: VS Code resolves settings in a strict priority order, and a committed .vscode/settings.json file overrides each developer's personal preferences for that project only.

The four layers, in priority order

Every setting in VS Code is resolved by checking four scopes, from lowest to highest priority:

1. Default settings — the built-in values shipped with VS Code. You cannot edit these; they are the fallback when nothing else defines a key.
2. User settings — your personal preferences, stored in a per-user file on your machine (for example, settings.json under your user profile's VS Code config directory). These apply to every window you open.
3. Workspace settings — stored in .vscode/settings.json inside the project folder. These override user settings for anyone who opens that folder.
4. Folder settings — in a multi-root workspace (a .code-workspace file listing several folders), each root folder can have its own .vscode/settings.json, which wins over the workspace-level file for resources under that folder only.

The practical consequence: a developer can keep their preferred 2-space indent globally while a project enforces 4 spaces, without either side changing anything manually.

A worked team configuration

Create .vscode/settings.json at the repository root and commit it. A realistic example for a JavaScript project:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "files.exclude": {
    "**/.DS_Store": true,
    "**/node_modules": true
  },
  "[python]": {
    "editor.tabSize": 4,
    "editor.defaultFormatter": "ms-python.python"
  }
}

Three things are worth noting in this file. First, editor.defaultFormatter pins which extension formats the code, so formatting output is identical across machines. Second, files.exclude hides noise like .DS_Store from the Explorer for everyone — these are display-only exclusions and do not affect search or Git. Third, the "[python]" block is a language-scoped setting: it applies only to files VS Code identifies as Python. This is the clean way to handle polyglot repositories where different languages have different conventions.

Because the formatter setting references an extension (esbenp.prettier-vscode), the setting silently does nothing for teammates who have not installed it. Pair the settings file with .vscode/extensions.json:

{
  "recommendations": [
    "esbenp.prettier-vscode",
    "ms-python.python"
  ]
}

VS Code will prompt anyone opening the folder to install the recommended extensions, closing the gap between "settings committed" and "settings actually working."

Editing paths: UI and JSON are the same store

The Settings UI and the JSON file are two views of one set of values. In the UI (File > Preferences > Settings), the User and Workspace tabs determine where a change is written — the Workspace tab writes to .vscode/settings.json. To see exactly which file a change lands in, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Preferences: Open Workspace Settings (JSON). No special permissions are needed beyond write access to the project folder.

Limits and common mistakes

• Application-scoped settings are ignored in workspace files. Some keys — window zoom level, update channel, and similar machine-level options — only make sense per installation. VS Code flags them with a warning if you put them in .vscode/settings.json; they will not take effect there.
• Do not commit machine-specific values. Absolute paths, local tool locations, and personal API endpoints belong in user settings. A committed path like /home/alice/tools/bin breaks or silently misconfigures everyone else's setup.
• Folder scope in multi-root workspaces surprises people. A folder-level setting applies only to files under that root folder. If you expect a workspace-wide effect, put the key in the .code-workspace file's settings section instead.
• Extension settings require the extension. As shown above, an uninstalled extension's settings are inert. Always pair shared settings with extension recommendations.
• Scoping rules can shift between releases. Setting names and which scope they support occasionally change. If a committed setting stops working after an update, hover over the key in settings.json — VS Code underlines unknown or mis-scoped keys.

Verify the layering yourself

A quick experiment confirms the priority order on your installed version. Pick a distinctive value, for example set "editor.tabSize": 8 in a test project's .vscode/settings.json while your user setting is 4. Open a file in that folder, press Tab, and check the indentation width in the status bar — it should show 8. Then open the Settings UI and flip between the User and Workspace tabs: the same key displays different values per scope. Close the folder and open a file elsewhere to confirm your user value still applies globally. That round trip is the whole mental model: defaults < user < workspace < folder, and the committed file is how a team turns that mechanism into shared conventions.