VS Code User Settings vs Workspace Settings: What Is the Difference?

User settings apply to every VS Code window you open. Workspace settings apply only to one project. When both define the same key, the workspace value wins.

This means you can keep your personal defaults in user settings. You only override what a specific project needs in workspace settings. You never touch your global setup for one project's rules.

Understanding this difference helps you decide where to put each setting. The current VS Code settings documentation also describes profile, remote, language-specific, and policy scopes that can affect the final value.

Main difference at a glance

Where settings are stored

The default profile's user settings live in a platform-specific folder:

• Windows: %APPDATA%\Code\User\settings.json
• macOS: $HOME/Library/Application Support/Code/User/settings.json
• Linux: $HOME/.config/Code/User/settings.json

Workspace settings live inside your project at .vscode/settings.json. If you are using a multi-root workspace, the settings are stored inside the .code-workspace file instead.

If you switch to a non-default VS Code profile, that profile has its own user settings under the User/profiles/<profile ID> directory. Open settings through VS Code when possible so you edit the active profile rather than the wrong file on disk.

How to open each scope

How precedence works

VS Code layers settings in a specific order. Each layer overrides the ones before it.

The result is that a workspace setting for Editor: Tab Size will override your user setting for the same key. But if you have not set it in workspace settings, your user value is used.

Settings that cannot be workspace-scoped

For security, VS Code blocks certain settings from being defined at the workspace level:

• git.path
• terminal.external.windowsExec
• terminal.external.osxExec
• terminal.external.linuxExec

The first time you open a workspace that tries to set these, VS Code shows a warning and ignores the values. This prevents a project you downloaded from redirecting your Git or terminal to an unexpected executable.

When to use user settings

Use user settings for preferences that are about you, not about the project:

• Editor font family and size
• Color theme and file icon theme
• Cursor style and blinking
• Whether the minimap is visible
• Keyboard shortcut preferences that affect your workflow

These settings make VS Code feel comfortable to you regardless of what project you are working on.

When to use workspace settings

Use workspace settings for rules that the project needs, regardless of who opens it:

• Indentation size and tabs vs spaces
• Which formatter to use for each language
• Files and folders to exclude from search and the Explorer
• Language-specific linting and formatting rules
• Formatter or linter settings when the team uses the required extension

Because workspace settings live in the .vscode folder, you can commit them to Git. Every contributor gets the same project rules automatically.

Override a user setting for one project

A common workflow: you prefer 2-space indentation everywhere, but one Python project requires 4 spaces.

Keep your user setting as 2 spaces by adding this line to your global settings.json:

json

{
  "editor.tabSize": 2
}

Now open the Python project. Inside its .vscode/settings.json file, add a workspace-level override that sets the tab size to 4 spaces instead:

json

{
  "editor.detectIndentation": false,
  "editor.tabSize": 4
}

When you open that project, the Status Bar indentation control shows Spaces: 4 for the active file. In other projects, your 2-space user default still applies. Disabling indentation detection in this workspace prevents an existing file's detected indentation from replacing the configured tab size.

Check which scope a setting uses

Select the User or Workspace tab in the Settings editor, then enter @modified in the search bar. The results show settings explicitly changed in that selected scope, and each modified row has a colored bar on the left.

Next steps

Now that you understand the difference, learn how to open and edit settings.json directly. If you work on multiple types of projects, VS Code profiles let you switch entire sets of settings at once.