Settings Sync

Settings Sync keeps your Visual Studio Code preferences consistent across devices. Use this article to turn on synchronization, choose which data to sync, restore or delete synced data, and troubleshoot synchronization and credential-storage issues.

Turn on Settings Sync

To turn on Settings Sync, follow these steps:

1. Select Backup and Sync Settings... from the Manage gear menu or the Accounts menu at the bottom of the Activity Bar.

   

2. Select the data that you want to synchronize.

   

3. Select Sign in, and then select a Microsoft or GitHub account.

   

4. If you are not already signed in with the selected account, complete the authentication flow in the browser.

After you sign in, Settings Sync automatically merges your local and cloud data and continues to synchronize changes in the background. If it cannot merge the data, you are prompted to resolve the conflicts.

Configure synced data

Run the Settings Sync: Configure... command or select Settings Sync is On > Settings Sync: Configure... from the Manage gear menu. Choose from the following data categories:

Exclude settings and extensions

To exclude a user setting from synchronization, use the setting's actions in the Settings editor or add the setting to the settingsSync.ignoredSettings Open in VS Code Open in VS Code Insiders setting.

To exclude an extension, use the extension's actions in the Extensions view (⇧⌘X (Windows, Linux Ctrl+Shift+X)) or add the extension to the settingsSync.ignoredExtensions Open in VS Code Open in VS Code Insiders setting.

Use the same keyboard shortcuts across operating systems

To use the same keyboard shortcuts on every operating system, clear the settingsSync.keybindingsPerPlatform Open in VS Code Open in VS Code Insiders setting.

Resolve conflicts

Conflicts can occur when you first turn on Settings Sync on a device or when you change data while a device is offline. Synchronization pauses until you resolve the conflicts.

The available actions depend on whether you are turning on sync or resolving a later conflict:

• Accept Local or Replace Remote uses your local data and overwrites the data in the cloud.
• Accept Remote or Replace Local uses the data in the cloud and overwrites your local data.
• Show Conflicts opens a diff editor where you can compare the local and remote data. Edit the merge result, and then select Complete Merge.

Switch accounts

To synchronize your data with a different account, run the Settings Sync: Turn Off command, and then turn on Settings Sync with the other account.

Synchronize Stable and Insiders

By default, the VS Code Stable and Insiders builds use separate Settings Sync services and do not share data. To share data between the builds, select the Stable sync service when you turn on Settings Sync in VS Code Insiders.

Restore synced data

VS Code stores local and remote backups of your preferences. You can use these backups to restore an earlier version of your data.

Run the Settings Sync: Show Synced Data command to view remote backups. To view local backups in the same view, open the Views submenu from the Settings Sync view overflow menu, and then select Sync Activity (Local).

To access local backups on disk, run the Settings Sync: Open Local Backups Folder command. The folder is organized by data category and contains timestamped versions of your JSON files.

Manage synced machines

VS Code tracks the devices that synchronize your data. Run the Settings Sync: Show Synced Data command, and then expand Synced Machines to view them.

Each device has a default name based on its operating system and whether it runs Stable or Insiders. Use the actions for a device to rename it or turn off Settings Sync remotely.

Turn off and delete synced data

To stop synchronizing on the current device, select Settings Sync is On > Settings Sync: Turn Off from the Manage gear menu, and then select Turn off.

To turn off synchronization on all your devices and remove your data from the service, select the checkbox labeled Turn off sync on all your devices and clear the data from the cloud. Then select Turn off. If you turn on Settings Sync again, it starts as a first-time setup.

Troubleshoot Settings Sync

Resolve data limits

Settings, keyboard shortcuts, and user tasks must each be 100 KB or smaller. You can synchronize up to 20 profiles. If your data exceeds a limit, Settings Sync reports an error and disables an affected category that was already synchronizing. Reduce the file size or number of profiles. Then turn on Settings Sync again, or run the Settings Sync: Configure... command to enable the affected category.

Troubleshoot credential-store issues

On desktop, Settings Sync stores authentication information by using the operating system credential store. This section uses keychain as a general term for a keychain, keyring, wallet, or credential store.

If the keychain is unavailable or misconfigured, restart VS Code with the following options to generate a verbose log:

code --verbose --vmodule="*/components/os_crypt/*=1"

Windows and macOS

Windows and macOS usually do not require additional keychain configuration. If the problem continues, report the issue and include the verbose log.

Linux

VS Code uses Chromium to detect the desktop environment and select a keyring. Search the verbose log for OSCrypt, password storage, or selected backend messages to identify the selected keyring.

GNOME or Unity

If the log contains Cannot create an item in a locked collection, unlock the default keyring, which is usually named Login. You can use a keyring manager such as Seahorse. The keyring must be unlocked when you sign in to the operating system.

KDE

Open KWalletManager and make sure that the default kdewallet wallet is open. If VS Code cannot connect to KWallet, try a keyring that implements the Secret Service API, as described in the next section.

Configure a keyring backend

To select a keyring backend manually, start VS Code with the password-store option. For example, install a keyring that implements the Secret Service API, and then run:

code --password-store="gnome-libsecret"

If the selected backend works, run Preferences: Configure Runtime Arguments from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and add "password-store": "gnome-libsecret" to the argv.json file.

The password-store option supports these values:

• kwallet5 for KWallet 5.
• gnome-libsecret for keyrings that implement the Secret Service API, such as GNOME Keyring, KWallet, and KeePassXC.
• kwallet for older KWallet versions.
• basic for basic text encryption. This option is not recommended.

If the desktop environment or keyring is not detected, report the issue and include the verbose log.

Configure basic text encryption

If you accept this risk, run Preferences: Configure Runtime Arguments from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and add "password-store": "basic" to the argv.json file.

Collect logs and report an issue

Settings Sync activity is recorded in the Log (Settings Sync) output channel. Authentication activity is recorded in the Account output channel.

When you report an issue, include the relevant output channels. For credential-store problems, also include the verbose log from the previous section.

Common questions

Is Settings Sync the same as the Settings Sync extension?

No. The Settings Sync extension by Shan Khan uses a private GitHub Gist to share settings. It is unrelated to the built-in Settings Sync feature.

What accounts can I use?

Settings Sync supports Microsoft and GitHub accounts. GitHub Enterprise Server accounts are not supported.

Can I use a different backend or service?

No. Settings Sync uses a dedicated service to store data and coordinate updates. Custom backends are not supported.

Related resources

• Configure user and workspace settings
• Create and manage profiles
• Synchronize extension global state