Fixing VS Code Settings Sync That Silently Overwrites Workspace-Specific Settings Across Machines

The Problem

VS Code's built-in Settings Sync feature is enabled across two or more machines for the same developer. A setting carefully configured for a specific project — a default formatter for that language, a Python interpreter path, an indentation size matching that codebase's convention — works correctly on the machine it was set on. Opening the same project on a different synced machine shows the setting reverted to something else, or the setting from one machine quietly overwrites the equivalent setting that had been deliberately configured differently on another. Nothing in the project's own repository changed; the setting itself moved, silently, as a side effect of sync running in the background.

Why It Happens

Settings Sync operates on User settings, not Workspace settings — and the two are easy to conflate

VS Code has multiple settings scopes: User (global, applies everywhere), Workspace (specific to one project, stored in .vscode/settings.json within that project), and Workspace Folder (for multi-root workspaces). Settings Sync only synchronizes the User scope. A setting a developer intended to be project-specific, but which was actually set at the User level (often because that's the default scope the Settings UI edits unless explicitly told otherwise), gets synced globally — meaning it follows the developer to every project on every machine, not just the one it was meant for.

The Settings UI defaults to editing the User scope unless a workspace is open and the tab is explicitly switched

The Settings editor has separate "User" and "Workspace" tabs, and it's easy to change a setting while the "User" tab happens to be selected — especially when quickly adjusting something via the command palette's "Preferences: Open Settings" rather than explicitly navigating to the Workspace tab first. The setting change succeeds either way, so there's no error to indicate it landed in the wrong scope.

Two machines syncing the same User-scoped setting will overwrite whichever was set more recently

Settings Sync's conflict resolution is based on the most recent change, not on which machine "should" own a given setting. If a setting is adjusted on Machine A and then independently adjusted differently on Machine B, whichever sync happened last simply overwrites the other — there's no merge or per-project awareness, because at the User scope there's no concept of "per-project" to begin with.

Extensions can also contribute settings, and not every extension respects the User/Workspace distinction consistently

Some extensions read only from User settings regardless of what's configured at the Workspace level, or vice versa, depending on how the extension itself was implemented — meaning even a setting correctly placed in .vscode/settings.json can still appear to be silently ignored or overridden if the specific extension in question doesn't honor workspace scope for that particular setting.

The Fix

1. Move project-specific settings into .vscode/settings.json explicitly

// .vscode/settings.json — committed to the repo, applies only to this project
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "python.defaultInterpreterPath": "./venv/bin/python",
  "editor.tabSize": 2
}

Settings that genuinely describe how to work on this specific codebase belong in the project's own .vscode/settings.json, committed to version control — this makes them apply consistently for every developer on the project, on every machine, entirely independent of each individual developer's Settings Sync state.

2. Explicitly use the Workspace tab when adjusting a project-specific setting through the UI

Command Palette → "Preferences: Open Workspace Settings"
(not "Preferences: Open Settings (UI)", which defaults to User scope)
Or: in the Settings editor, click the "Workspace" tab explicitly before changing a value

Deliberately opening Workspace settings specifically, rather than the generic settings command that defaults to User scope, is the direct way to ensure a change lands where it was actually intended — worth making a habit of for any setting that's genuinely about one project rather than personal preference.

3. Audit User settings for anything that should have been workspace-scoped

# Open the global settings.json directly and review its contents
code ~/Library/Application Support/Code/User/settings.json  # macOS
code ~/.config/Code/User/settings.json  # Linux

Reviewing the raw User settings.json file directly surfaces anything that's actually project-specific but ended up at the global level — formatter choices, interpreter paths, or language-specific tab sizes are common candidates worth moving to the relevant project's .vscode/settings.json once spotted here.

4. Use Settings Sync's selective sync configuration to exclude categories prone to this confusion

Command Palette → "Settings Sync: Configure"
Review which categories are included — Settings, Keybindings, Extensions, UI State, etc.
Consider excluding or being more deliberate about syncing Settings if project-specific
drift keeps recurring

Settings Sync allows excluding specific categories from syncing; for a team or individual that keeps running into this specific problem, being more selective about what actually syncs — rather than syncing everything by default — trades some convenience for predictability where it matters most.

Why This Works

Each fix addresses a different point where the User/Workspace scope boundary gets blurred. Moving settings into the committed .vscode/settings.json removes them from Settings Sync's reach entirely, making them a property of the project rather than the developer's synced profile; using the Workspace tab deliberately prevents the mistake at the point a setting is actually changed; auditing existing User settings catches drift that already happened; and selective sync configuration addresses the problem at the tool-configuration level for cases where the mistake keeps recurring despite care.

Conclusion

Settings Sync overwriting a project-specific setting isn't a sync bug — it's a setting that was configured at the User scope when it should have been scoped to the Workspace, which Settings Sync (correctly, for its actual job) then propagates across every machine as if it were a personal preference. Move genuinely project-specific settings into the committed .vscode/settings.json, use the Workspace settings tab deliberately rather than the default User-scoped settings command, audit existing User settings for anything that drifted there by mistake, and consider selectively excluding settings from sync if this keeps recurring despite care.