← Back to Guides

GUIDE

How to sync iTerm2 settings across Macs

How to sync iTerm2 settings across multiple Macs with Synclet (ex ConfigMesh), including profiles, key mappings, color presets, dynamic profiles, and Python scripts.

August 24, 2026Tags: macositerm2terminalsyncguides

If you use iTerm2 on more than one Mac, Synclet (ex ConfigMesh) can keep your profiles, keybindings, and colors identical everywhere with encrypted sync.

iTerm2 has no built-in cloud sync. Its own answer is "Load preferences from a custom folder or URL", which means pointing every Mac at a folder you have to keep in sync yourself. Synclet is that missing half — it does the syncing, end-to-end encrypted, without putting your terminal configuration in a third party's plaintext.

What gets synced

The iTerm2 bundle covers:

  • Profiles — every profile, including working directories, commands, and badges
  • Key mappings — global and per-profile shortcuts
  • Color presets — themes you have imported or built
  • Window and font settings — appearance, transparency, and layout
  • Dynamic profiles — JSON profiles dropped in by you or by other tools
  • Scripts — iTerm2 Python API automation

These live in two places:

~/Library/
├── Application Support/iTerm2/
│   ├── DynamicProfiles/
│   └── Scripts/
└── Preferences/
    └── com.googlecode.iterm2.plist

Almost everything you configure in Settings lands in com.googlecode.iterm2.plist. Imported .itermcolors presets are merged into that same file rather than kept as separate files, so syncing the plist carries your themes with it.

Before you start: quit iTerm2

This is the one iTerm2-specific gotcha, and skipping it is the usual reason a sync appears to do nothing.

iTerm2 holds its preferences in memory while running and writes them out when it quits. If you sync while it is open, you can upload a stale plist, and a plist that arrives on a running instance gets overwritten when that instance quits.

So, on every Mac: quit iTerm2 completely before syncing, and run the sync from another terminal (Terminal.app, Ghostty, or the Synclet menu bar app).

Step 1: Download Synclet (ex ConfigMesh) for macOS

Install the latest macOS build:

Sign in after installing.

Step 2: Create the iTerm2 bundle

Create a new bundle and set the root to:

  • Library/

Then add these include rules:

  • Application Support/iTerm2/DynamicProfiles
  • Application Support/iTerm2/DynamicProfiles/**
  • Application Support/iTerm2/Scripts
  • Application Support/iTerm2/Scripts/**
  • Preferences/com.googlecode.iterm2.plist

That covers your preferences, dynamic profiles, and scripts.

If you only care about profiles, keybindings, and colors, the single com.googlecode.iterm2.plist rule is enough on its own.

Step 3: Hit Sync

With iTerm2 quit, click Sync on your first Mac, then run Sync on your other Mac(s) using the same account and encryption passphrase. Reopen iTerm2 afterwards and your profiles, keys, and colors will match.

Leaving the custom-folder setting alone

If you previously set Settings → General → Preferences → Load preferences from a custom folder or URL, turn it off before syncing the plist. Otherwise iTerm2 reads from your custom folder and ignores the com.googlecode.iterm2.plist that Synclet manages, and the two will quietly disagree.

Pick one mechanism. If Synclet is syncing the plist, iTerm2 should be using its default preferences location.

What is not covered

Shell configuration is separate from iTerm2 itself. Your .zshrc, .bashrc, oh-my-zsh setup, and starship or powerlevel10k themes are dotfiles in your home directory, not iTerm2 preferences — sync those with a dotfiles bundle. See How to use Synclet (ex ConfigMesh) to sync your dotfiles (encrypted).