Where to Find Warp Configuration Files: Complete Directory Guide

Warp stores configuration files in platform-specific directories, with portable user data located in ~/.warp on macOS and ~/.local/share/warp on Linux, while non-portable settings live in ~/.config/warp on Linux and within the same .warp folder on macOS.

Warp is a Rust-based terminal emulator that organizes user customizations across distinct directory types depending on data portability requirements. Understanding exactly where Warp configuration files reside is essential for backing up themes, syncing workflows across machines, or manually editing settings.toml. The canonical path resolution logic lives in warp_core::paths, specifically within crates/warp_core/src/paths.rs.

Core Configuration Directories in Warp

The Warp source code defines three primary directory types that separate portable assets from machine-specific settings. These are computed at runtime based on the host operating system.

Portable User Data Directory

Portable user data includes themes, workflows, launch configurations, and tab configurations that can be safely synced between machines. According to the source in crates/warp_core/src/paths.rs, the data_dir() function returns this location:

• macOS: ~/.warp (or ~/.warp-dev for development builds)
• Linux: $XDG_DATA_HOME/warp (typically ~/.local/share/warp)
• Windows: %LOCALAPPDATA%\Warp\Warp

This directory contains subfolders like themes/, workflows/, launch_configurations/, and tab_configs/.

Non-Portable Configuration Directory

Non-portable config files include machine-specific preferences such as settings.toml, keybindings.yaml, and user_preferences.json. The config_local_dir() function in crates/warp_core/src/paths.rs resolves these paths:

• macOS: Same as the data directory (~/.warp)
• Linux: $XDG_CONFIG_HOME/warp (typically ~/.config/warp)
• Windows: %APPDATA%\Warp\Warp\config

Legacy Home-Relative Configuration

For backward compatibility, Warp maintains a legacy home-relative path accessed via warp_core::paths::warp_home_config_dir(). On non-macOS platforms, this resolves to hidden folders like ~/.warp in the user’s home directory, though modern builds prefer the XDG-compliant paths on Linux.

Where to Find Specific Warp Configuration Files

The high-level façade used throughout the application resides in app/src/user_config/mod.rs, which forwards calls to the core path helpers. Here are the exact file locations derived from the source analysis:

Settings and Preferences

The primary settings file is located at:

warp_core::paths::config_local_dir().join("settings.toml")

User preferences (window state, onboarding flags) live at:

warp_core::paths::config_local_dir().join("user_preferences.json")

Both paths are referenced in app/src/settings/mod.rs.

Keybindings

Custom keyboard shortcuts are stored in:

warp_core::paths::config_local_dir().join("keybindings.yaml")

This resolution is defined in app/src/keyboard.rs.

Custom Themes and Workflows

User-installed themes reside in the portable data directory:

warp_core::paths::data_dir().join("themes")

Workflows follow the same pattern:

warp_core::paths::data_dir().join("workflows")

Launch and Tab Configurations

Session management configs are also stored as portable data:

warp_core::paths::data_dir().join("launch_configurations")
warp_core::paths::data_dir().join("tab_configs")

These paths are wrapped by helper functions in app/src/user_config/mod.rs, such as themes_dir() and launch_configs_dir().

Platform-Specific Path Reference

macOS

On macOS, both portable and non-portable data converge in the home directory:

• Data Directory: ~/.warp/ (contains themes/, workflows/, settings.toml)
• Config Directory: Same as above (~/.warp/)

The macos_config_dir_name() helper appends the appropriate suffix (e.g., .warp vs .warp-dev) based on the build channel.

Linux

Linux follows the XDG Base Directory Specification strictly:

• Portable Data: ~/.local/share/warp/ (or $XDG_DATA_HOME/warp/)
• Settings: ~/.config/warp/ (or $XDG_CONFIG_HOME/warp/)
• Legacy: ~/.warp/ (maintained for migration purposes)

Windows

Windows separates data using standard app data folders:

• Portable Data: %LOCALAPPDATA%\Warp\Warp\ (e.g., C:\Users\<User>\AppData\Local\Warp\Warp\)
• Settings: %APPDATA%\Warp\Warp\config\ (e.g., C:\Users\<User>\AppData\Roaming\Warp\Warp\config\)

Accessing Config Paths Programmatically

If building plugins or scripts that interact with Warp, use the core path utilities directly:

use warp_core::paths;

/// Retrieve the full path to settings.toml
fn get_settings_path() -> std::path::PathBuf {
    paths::config_local_dir().join("settings.toml")
}

To enumerate all installed themes:

use std::fs;

fn list_themes() -> std::io::Result<Vec<std::path::PathBuf>> {
    let themes_dir = warp_core::paths::themes_dir();
    let mut themes = Vec::new();
    
    for entry in fs::read_dir(themes_dir)? {
        let entry = entry?;
        if entry.path().extension().map_or(false, |ext| ext == "json") {
            themes.push(entry.path());
        }
    }
    Ok(themes)
}

To ensure a launch configuration directory exists before writing:

use warp_core::paths;
use std::fs;

fn ensure_launch_config_dir() -> std::io::Result<std::path::PathBuf> {
    let dir = paths::data_dir().join("launch_configurations");
    fs::create_dir_all(&dir)?;
    Ok(dir)
}

Summary

• Portable data (themes, workflows, launch configs) lives in ~/.warp on macOS, ~/.local/share/warp on Linux, and %LOCALAPPDATA%\Warp\Warp on Windows, computed by warp_core::paths::data_dir().
• Non-portable settings (keybindings, preferences, settings.toml) reside in ~/.config/warp on Linux and the same .warp folder on macOS, returned by warp_core::paths::config_local_dir().
• Source implementation is located in crates/warp_core/src/paths.rs, with high-level wrappers in app/src/user_config/mod.rs.
• Specific files: settings.toml and user_preferences.json are in the config directory, while custom themes and workflows go in the data directory subfolders.

Frequently Asked Questions

Can I symlink Warp's configuration directory to sync across machines?

Yes. Because Warp separates portable data (themes, workflows) from non-portable configs (window positions, machine-specific paths), you can safely symlink ~/.warp on macOS or ~/.local/share/warp and ~/.config/warp on Linux to a Dropbox or Git repository. Avoid symlinking the entire application data folder on Windows, as it contains compiled caches alongside configs.

Why does Warp use different directories for settings and themes?

Warp distinguishes between portable and non-portable data to support seamless synchronization. Themes and workflows are shareable across devices, while settings.toml might contain absolute paths or OS-specific preferences that should remain local. This architecture is enforced by the data_dir() and config_local_dir() functions in crates/warp_core/src/paths.rs.

Where does Warp store crash logs or debug information?

Crash logs and telemetry data are typically stored outside the user-editable configuration directories, often in platform-specific cache or log locations. While the user_preferences.json in the config directory tracks UI state and onboarding completion, detailed crash dumps are written to Warp's internal log folders, which are distinct from the configuration paths defined in app/src/settings/mod.rs.

How do I reset Warp to default settings?

To completely reset Warp, delete the configuration directories returned by warp_core::paths::config_local_dir() and warp_core::paths::data_dir(). On macOS, this means removing ~/.warp; on Linux, delete both ~/.config/warp and ~/.local/share/warp. Restarting Warp will regenerate these directories with default values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}