DEV Community

Cover image for VS Code Settings Sync: Basics, Troubleshooting, and More
Emmanuel Aiyenigba
Emmanuel Aiyenigba

Posted on

VS Code Settings Sync: Basics, Troubleshooting, and More


The introduction of Settings Sync as a built-in functionality lets you share your VS Code configurations across multiple machines and not worry about installing dependencies afresh or environment configuration when working on another machine or with your team.

This was added into version 1.48.0 released in July 2020. Previous versions had no such functionality built in. Before the release of version 1.48.0, if you needed to synchronize settings across your machines, you would have to install an extension from the marketplace.

This post will cover everything you need to know to get started with Settings Sync in Visual Studio Code. You’ll learn how to take advantage of Settings Sync to boost productivity. At the end of this post, you’ll understand the nitty-gritty of Settings Sync and gain the necessary knowledge needed to begin using it. Given these points, let’s dive into Settings Sync in detail.

What Is Settings Sync on VS Code?

Setting Sync is a VS Code built-in functionality that allows you to share and use your preferences across multiple machines. You can sync preferences such as Settings, Keyboard Shortcuts, User Snippets, Extensions, and UI State. VS Code Settings Sync is not the same as the Settings Sync extension built by Shan Khan, which stores your settings in a private Gist on GitHub. The VS Code Settings Sync stores your synced settings on the cloud.

It is recommended that you use the built-in Settings Sync and not the Settings Sync extension. This is because you can do so much with the former, plus it is maintained by the Visual Studio Code team so you can expect it to get constant improvements to better serve your development needs.

You can choose to sync settings to either your GitHub or Microsoft account. The Microsoft account could be either your Outlook or Azure account. It is equally important to note that VS Code does not support GitHub Enterprise accounts for Settings Sync; use either a personal account or an organization account. Without delay, let’s go into how you can sync your VS Code settings.

Importance of Settings Sync

Undoubtedly, VS Code Settings Sync has a lot of importance for individuals and teams working on the same project. Individuals who prefer to use more than one machine for work can do so while maintaining the same settings across their machines.

This is to say that if you are using machine A for work now and will be working with machine B later (probably because you’re in another location and didn’t take machine A with you), if you have Settings Sync turned on in machine A, you can merge your settings preferences that you have to your account on the cloud by signing in to the account (GitHub or Microsoft) your data was synced to. This way, you don’t need to install your favorite extensions, configure your choice development environment, or organize your UI State on your current machine.

Because of Settings Sync, teams scattered across the world but working on the same project can use the same settings on their machines at the workspace level by creating a .vscode folder with a setting.json file containing the settings you want to share with your team.


Other Important Features of Settings Sync

Settings Sync gives you the flexibility of working from any of your machines while maintaining your preferred VS Code environment.
It saves you the stress of reinstalling your favorite setup if you lose your machine or have to work with another machine.
You and your team can share the same work environment. Sounds cool, right?

Your settings are protected. VS Code doesn’t jeopardize your data privacy; you can always turn off Settings Sync and have your data wiped out of the cloud.
You don’t need to install a marketplace extension to synchronize settings across your machines.
With Settings Sync, you get to choose your preferences (the things you want to sync) and leave out the things you don’t want to sync.
Furthermore, VS Code always stores a local and remote backup. In case something goes wrong, you can restore your data.

How Do I Sync My VS Code Settings?

  • Open an instance of VS Code then click on the Manage gear.
  • Select Turn on Settings Sync.

turn on settings sync

  • Select your preferences (the data you want to sync).

select preferences

Note: The following UI State options are currently available for syncing (more might be added in the future): Panel entries, Activity Bar entries, Display Language, Views layout and visibility, Recently used commands, and Do not show notification again.

  • After selecting your preferences, click Sign in & Turn on. You will be asked to choose between your GitHub or Microsoft account for signing in.

choose account

After you select the account to sign in, an authentication screen will pop up. Settings Sync turns on after you sign in. At this point, you have Settings Sync enabled and your preferences activities will be synced in the background from time to time.

Now that you’re signed in and synced, you can manage your synchronization preferences at will. To do that, click the Manage gear > Setting Sync is On > select Settings Sync: Configure. VS Code gives you the flexibility to sync your data to a different account any time you want. This is to say that you can change your sync account from GitHub to Microsoft and vice versa at will. To do this, turn off then turn on Settings Sync again, then select a different account (GitHub or Microsoft).

Syncing Options

When you turn on Settings Sync on one machine, signing in to the account that was synced to and turning on Settings Sync on another machine will automatically present to you a dialog. You have the option to Merge, Replace Local, or Merge Manually.

  • Merge: This option merges the settings on your local machine (local settings) with the settings on the cloud (remote settings). It combines the settings of your local and cloud environments for use on your current machine.

  • Replace Local: Selecting this option replaces your local settings with your remote settings. You should be sure you don’t need any of your local settings before selecting this option; otherwise you should merge.

  • Merge Manually: This option allows you to select the settings you want to merge. You can choose your preferences manually then merge them. You’ll have the liberty to go through each entry to choose the settings you want to merge. It shows you a few JSON files that you can edit to meet your preferences: settings.json (Settings), keybindings.json (Keyboard Shortcuts), typescript.json (User Snippet), and extensions.json (Extensions).

Data Privacy

Without a doubt, your data is protected on the cloud and lives under your rules. Therefore, you can decide to clear it from the cloud any time you like. You alone have access to your data through the account(s) you synced to. It is recommended you clear your data when you turn off Settings Sync. Sometimes you don’t want certain data to persist on the cloud when you turn off Settings Sync, probably due to its sensitivity. So you can clear it out of the cloud. For example, you might not want certain data in your UI State, such as activity bar entries that give indicators like the number of outgoing Git changes, to persist on the cloud once you turn off sync.

Some extensions store important data such as Git history, which gives a visual of the Git log and allows you to compare branches and commits. It’s good to wipe out your data when you turn off sync. If you decide to turn on sync again, your data is synced afresh.

To turn off Settings Sync and clear out data, go to the Manage gear, click on Setting Sync is On, then select Setting Sync: Turn Off and select the checkbox to wipe out your cloud data. With this in mind, let’s take a look at the levels at which Settings Sync occurs.

Levels at Which Settings Sync Occurs

At this point, it’s important to state that Settings Sync in VS Code occurs at different levels and later settings override earlier settings. According to the VS Code official documentation, Settings Sync occurs at the following levels.

  • Default settings: Default settings come with a newly downloaded Visual Studio Code.

  • User settings: Global settings that override the default settings and apply to all VS Code windows.

  • Remote settings: This applies to a remote machine - utilizing cloud development environments to manage your projects. You can sync settings to a remote machine. These settings can be used across your team. Remote teams can collaborate better by storing Sync Settings in a virtual machine, to be shared by members of the team at the workspace level.

  • Workspace settings: These settings apply at the workspace level. It overrides the previous settings. This is useful for helping developers collaborate on a project by using the same setting and without globally overriding their personal preferences.

  • Workspace folder settings: This applies to a specific folder in a multi-root workspace

Resolving Synchronization Conflicts

It’s important to realize that conflict may happen when syncing settings between more than one machine. There will be sync conflict when changes occur when a machine is offline. This is because the changes can not be uploaded to the remote environment if the local machine is offline (without an internet connection). To point out, when conflicts occur, you can either Accept Local, Accept Remote, or Show Conflicts.

  • Accept Local will replace remote settings with local settings.

  • Accept Remote will replace local settings with remote settings.

  • Show Conflicts will open a “diff” editor where you can preview the local and remote settings and then choose either to accept local or accept remote.


Tracking Sync Activities

Another key point to note is that VS Code tracks sync data by default and stores local and remote backups of your preferences, which allows you to undo an action or restore your data if anything goes wrong. A local backup folder is created to track your local changes. The local backup is automatically deleted after 30 days, while for the remote backup, only the latest 20 versions of each individual resource are retained.

The machines synchronizing your preferences are tracked and given a default name based on their platform and the type of VS Code they’re using (Insiders or Stable). You can turn off preferences sync for any of the synced machines at any time. To see sync activities and sync machines, click the Manage gear > Setting Sync is On > select Settings Sync: Show Synced Data.

Troubleshooting Settings Sync

Undeniably, you can sometimes run into issues when using Settings Sync. The following is how to troubleshoot a few common issues.

  • Error while turning on Settings Sync. No authentication providers.
    This error usually occurs in Linux. This error happened because org.freedesktop.secrets was not provided by any .service files. Gnome provides org.freedesktop.secrets in many desktop environments, so to resolve this issue, install gnome-keyring, libsecret, and libgnome-keyring.

  • Turning on Settings Sync immediately gets a request failed error.
    This happens on rare occasions when turning on Settings Sync for the first time. Another attempt to turn on Settings Sync should succeed.


In conclusion, VS Code Settings Sync allows you to synchronize your favorite preferences such as Settings, Keyboard Shortcuts, User Snippets, Extensions, and UI State and reuse them on any of your machines. With this, you don’t have to worry about reconfiguring your favorite environment to your new machine. Remote teams can collaborate more effectively by using Settings Sync. And your data lives under your rules; therefore, you can turn off Settings Sync and wipe your data from the cloud when you feel it’s necessary to do so.

Do you need help creating technical content for your developer audience? Reach out and let’s work together.

Shameless Plug

If you find my content valuable and engaging, consider sharing it with your network and follow me here and on Twitter. It would mean a lot to me.

I just launched my newsletter where I’ll be sharing carefully curated technical articles and development news. If you enjoy learning about Open source software, Web engineering, Software engineering, Cloud & DevOps and other aspects of product engineering, please join my readers’ list.

Emmanuel’s Substack | Emmanuel Aiyenigba | Substack

Carefully curated engineering articles, open source software updates and development news worth knowing about. Click to read Emmanuel’s Substack, by Emmanuel Aiyenigba, a Substack publication. Launched 8 days ago.


Top comments (0)