Settings Sync stores custom theme selection as absolute paths, breaking cross-platform sync

[nisavid]

Summary

Settings Sync stores custom theme selections as absolute file paths. When the same Warp account is used on macOS and Linux, a custom theme selected on one platform does not work on the other because Warp's supported custom theme directories are platform-specific.

Problem

A user syncs Warp settings between macOS and Linux and has the same custom theme YAML files installed on both systems. The selected custom theme is written to settings.toml under appearance.themes.selected_system_themes with a custom.path value. That path is absolute and OS-specific.

Documented theme locations differ by platform:

• macOS: ~/.warp/themes/
• Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/

As a result, choosing the custom theme on macOS syncs a path like /Users/ivan/.warp/themes/catppuccin_mocha.yml, which Linux does not treat as the active discovered theme. Choosing the theme on Linux syncs a path like /home/nisavid/.local/share/warp-terminal/themes/catppuccin_mocha.yml, which macOS cannot use.

This makes Settings Sync fight itself for users who use the same custom themes across multiple OSes.

Expected behavior

Warp should allow custom theme selection to sync across platforms when the same theme is installed on each platform, without requiring users to make fake absolute paths.

Possible acceptable product behavior would be one of:

• Sync custom theme selection by stable identity, such as theme name plus theme type, instead of absolute file path.
• Treat custom theme selection as platform-specific/device-specific, like other platform-specific settings.
• Resolve synced custom theme paths through each platform's documented theme directory when a matching theme exists.

Actual behavior

The selected custom theme is synced using an absolute path. The setting only works on the OS whose absolute path is stored in Settings Sync.

Observed behavior from the Linux side:

• When settings.toml was manually changed to macOS-style paths under /Users/ivan/.warp/themes/*.yml, Warp did not use the custom themes on Linux.
• Creating a symlink at /Users/ivan/.warp/themes pointing to the Linux theme directory did not make Warp accept the macOS paths.
• Reversing the symlink so the real files lived under /Users/ivan/.warp/themes and Linux's theme directory pointed there also did not work.
• Bind-mounting the Linux theme directory at /Users/ivan/.warp/themes also did not work, even though both paths had the same device and inode and the configured files were readable.
• After selecting the themes in the Linux theme picker, Warp rewrote the synced value back to the Linux-discovered paths and updated the cloud preference with those paths.

Example values that get synced:

[appearance.themes]
selected_system_themes = {
  dark = { custom = { name = "Catppuccin Mocha", path = "/Users/ivan/.warp/themes/catppuccin_mocha.yml" } },
  light = { custom = { name = "Catppuccin Latte", path = "/Users/ivan/.warp/themes/catppuccin_latte.yml" } },
}

On Linux, selecting the same themes rewrites them to:

[appearance.themes]
selected_system_themes = {
  dark = { custom = { name = "Catppuccin Mocha", path = "/home/nisavid/.local/share/warp-terminal/themes/catppuccin_mocha.yml" } },
  light = { custom = { name = "Catppuccin Latte", path = "/home/nisavid/.local/share/warp-terminal/themes/catppuccin_latte.yml" } },
}

Reproduction steps or desired workflow

1. Install the same custom theme YAML files on macOS and Linux using Warp's documented custom theme directories.
2. Enable Settings Sync on the same Warp account on both OSes.
3. On macOS, select a custom theme from ~/.warp/themes/.
4. Let Settings Sync propagate the selection to Linux.
5. Observe that Linux receives the macOS absolute path in the selected custom theme setting and the theme does not work as expected.
6. On Linux, select the same custom theme from ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/.
7. Let Settings Sync propagate the selection to macOS.
8. Observe that macOS receives the Linux absolute path and the theme no longer works there.

Artifacts

None attached.

Warp version

v0.2026.04.27.15.32.stable_03

Operating system

Observed on Linux: CachyOS, kernel/version 7.0.1-1-cachyos.

Also affects sync with macOS. macOS version is unknown; the macOS home directory in the user's setup is /Users/ivan.

[oz-for-oss]

@nisavid

This issue appears to overlap with existing issues:

• Settings Sync causes custom theme to revert to default on other machine #8988 — Settings Sync causes custom theme to revert to default on other machine
• Custom Theme Path Resolution #6678 — Custom Theme Path Resolution

If this report is meaningfully different, please comment with the additional context or distinguishing behavior so a maintainer can review it. Otherwise, a maintainer may close it as a duplicate after review.

Maintainer details

I concluded that settings Sync stores custom theme selections as absolute local paths, causing custom themes to fail across devices/platforms; this matches existing reports #8988 and #6678..

Duplicate reasoning

• Settings Sync causes custom theme to revert to default on other machine #8988: Reports Settings Sync propagating a custom theme selection to another machine where the same custom theme is installed, but the receiving machine cannot resolve it and falls back to the default theme.
• Custom Theme Path Resolution #6678: Reports that synced custom theme selections use fully qualified paths tied to a specific home directory and requests resolving them relative to the custom themes root for cross-machine/platform sync.

This is my automated analysis and may be incorrect. A maintainer will verify the details.

Powered by Oz

[ivan-systalyze]

Additional clarification from testing on macOS:

This issue is specifically about syncing the custom theme reference or selection metadata, not syncing custom theme files. The same theme files are already installed on both systems. On macOS they exist in Warp's documented custom theme directory:

• /Users/ivan/.warp/themes/catppuccin_frappe.yml
• /Users/ivan/.warp/themes/catppuccin_latte.yml
• /Users/ivan/.warp/themes/catppuccin_macchiato.yml
• /Users/ivan/.warp/themes/catppuccin_mocha.yml

The current synced macOS settings.toml can still contain Linux absolute paths under appearance.themes.selected_system_themes, for example /home/nisavid/.local/share/warp-terminal/themes/catppuccin_mocha.yml, even though the same basename exists locally under /Users/ivan/.warp/themes/.

Because Warp uses a specific custom theme directory per OS, a portable sync format could store a reference such as the filename/basename (catppuccin_mocha.yml, catppuccin_latte.yml) or another stable theme identity, then resolve it relative to each platform's supported custom theme directory. The problematic part is syncing absolute OS-specific paths like /Users/... or /home/..., not the absence of the YAML files.

Additional macOS environment where this was observed:

• Warp: v0.2026.04.27.15.32.stable_03
• macOS: 26.4.1, build 25E253
• Darwin: 25.4.0, arm64
• macOS custom theme directory: /Users/ivan/.warp/themes/

[nisavid]

Additional note on the possible overlap with #8988 and #6678:

Those do appear to be reports of the same general class of problem: Settings Sync stores custom theme selections using machine-specific paths. The distinction is scope. Both related reports seem centered on custom theme sync across macOS installations where the path differs by username or home directory, for example /Users/<username>/.warp/themes/....

This issue is meant to make sure the cross-platform case is covered too. A fix that only normalizes macOS home-directory paths, or expands/collapses ~ for macOS paths, could plausibly close #8988 and #6678 while still leaving Linux/macOS sync broken, because the supported custom theme roots differ by OS:

• macOS: ~/.warp/themes/
• Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/

PR #9634 (fix(themes): Handle tilde in theme paths) looks like it may help the macOS-username version of this by handling tilde paths. That would be useful, but it would not by itself make a synced reference portable between /Users/.../.warp/themes/... and /home/.../.local/share/warp-terminal/themes/....

The requirement for this issue is therefore not just "make absolute paths less username-specific". It is "sync the selected custom theme by a portable reference" — for example a basename such as catppuccin_mocha.yml, or another stable theme identity — and resolve that reference under each platform's documented custom theme directory.