> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Settings file

Configure Warp with a plain-text TOML settings file. Learn where it lives, how it works with the Settings panel, and see common configuration examples.

Warp stores your preferences in a plain-text file called `settings.toml`. You can edit it directly in any text editor, check it into version control, or generate it with a script. Changes take effect immediately — no restart required.

The settings file works alongside the graphical Settings panel. Changes you make in either place are reflected in the other.

**Key features:**

-   **Hot-reload** — Warp watches `settings.toml` for changes and applies them instantly when you save the file.
-   **Error recovery** — If the file contains invalid TOML or an unrecognized value, Warp shows a warning banner and falls back to defaults for the affected settings. Fix the file and the banner clears automatically.
-   **Automatic migration** — When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`.
-   **Bidirectional sync with Settings UI** — Changes in the Warp **Settings** panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) write to `settings.toml`, and hand-edits to the file are reflected in the panel.
-   **Agent-powered editing** — Ask Warp’s agent to change settings for you using natural language (for example, “increase my font size to 16”). The bundled `modify-settings` skill handles the file update automatically.

## Opening your settings file

There are several ways to open `settings.toml`:

-   In the Warp app, go to **Settings** and click **Open settings file** at the bottom of the panel.
-   Open the file directly in any editor at the path listed below for your platform and Warp release channel.

## File location

Depending on your platform and Warp release channel, `settings.toml` is located at:

-   **macOS**
    -   Stable — `~/.warp/settings.toml`
    -   Preview — `~/.warp-preview/settings.toml`
-   **Linux**
    -   Stable — `~/.config/warp-terminal/settings.toml`
    -   Preview — `~/.config/warp-terminal-preview/settings.toml`
-   **Windows**
    -   Stable — `%LOCALAPPDATA%\warp\Warp\config\settings.toml`
    -   Preview — `%LOCALAPPDATA%\warp\WarpPreview\config\settings.toml`

## Settings file format

The file uses [TOML v1.1](https://toml.io/en/v1.1.0) syntax. Settings are organized into **sections** (TOML tables) that group related options — for example, `[appearance.text]` contains font settings and `[agents.profiles]` contains agent permission settings.

Here is a minimal example showing the structure:

```
# Appearance settings[appearance.text]font_name = "JetBrains Mono"font_size = 14.0line_height_ratio = 1.3
[appearance.themes]theme = "dracula"
# Terminal behavior[terminal.input]syntax_highlighting = truehonor_ps1 = false
# Agent permissions[agents.profiles]agent_mode_execute_readonly_commands = true
```

### How sections map to TOML tables

Each section in the settings file corresponds to a TOML table header in brackets. Subsections use dot-separated paths:

-   `[general]` — Top-level general settings like session restoration and tab placement
-   `[appearance]` — Visual settings, with subsections like `[appearance.text]`, `[appearance.themes]`, `[appearance.cursor]`
-   `[agents]` — Agent and AI settings, with subsections like `[agents.profiles]`, `[agents.warp_agent.input]`
-   `[terminal]` — Terminal behavior settings, with subsections like `[terminal.input]`

For the complete list of every available setting, see [All settings reference](/terminal/settings/all-settings/).

## How settings are applied

### Relationship between the Settings panel and the file

The Warp Settings panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) and `settings.toml` represent the same underlying configuration. Changing a toggle in the Settings panel writes the new value to `settings.toml`. Editing `settings.toml` by hand updates the Settings panel the next time it reads the file.

### Error banner

When `settings.toml` has errors, Warp displays a dismissible warning banner at the top of the workspace. The banner includes an **Open settings file** button so you can jump directly to the file and fix the issue. Once you save a corrected file, the banner disappears automatically.

## Common configurations

### Change theme and font

```
[appearance.themes]theme = "cyber_wave"
[appearance.text]font_name = "Fira Code"font_size = 15.0ligature_rendering_enabled = truefont_weight = "normal"
```

### Configure agent permissions

```
[agents.profiles]agent_mode_coding_permissions = "always_allow_reading"agent_mode_execute_readonly_commands = trueagent_mode_command_execution_allowlist = [  "cat(\\s.*)?",  "echo(\\s.*)?",  "find .*",  "grep(\\s.*)?",  "ls(\\s.*)?",  "which .*",]
```

### Enable Vim keybindings

```
[text_editing]vim_mode_enabled = truevim_status_bar = true
```

## Migrating from previous settings

When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`. No action is required — your customizations carry over and the file becomes the source of truth for all settings going forward.

## Troubleshooting

### ”Your settings file contains an error” banner

This banner appears when `settings.toml` has invalid TOML syntax or an unrecognized value. Click **Open settings file** in the banner to open the file and look for:

-   **Missing quotes** — String values must be wrapped in double quotes: `font_name = "Hack"`, not `font_name = Hack`.
-   **Missing brackets** — Section headers require square brackets: `[appearance.text]`.
-   **Wrong value types** — Check that numbers are numbers (`font_size = 13.0`), booleans are `true`/`false`, and enum values are valid strings.

### Resetting to defaults

Delete `settings.toml` (or rename it) and restart Warp. Warp falls back to built-in defaults for all settings. The file is re-created the next time you change a setting through the Settings panel.

```
# Uncomment the two lines that match your platform and Warp release# channel, then run them to back up and delete settings.toml.
# Stable (macOS)# cp ~/.warp/settings.toml ~/.warp/settings.toml.bak# rm ~/.warp/settings.toml
# Stable (Linux)# cp ~/.config/warp-terminal/settings.toml ~/.config/warp-terminal/settings.toml.bak# rm ~/.config/warp-terminal/settings.toml
# Preview (macOS)# cp ~/.warp-preview/settings.toml ~/.warp-preview/settings.toml.bak# rm ~/.warp-preview/settings.toml
# Preview (Linux)# cp ~/.config/warp-terminal-preview/settings.toml ~/.config/warp-terminal-preview/settings.toml.bak# rm ~/.config/warp-terminal-preview/settings.toml
```

### Settings not applying

Confirm you’re editing the correct file for your platform and Warp release channel (see [File location](#file-location) above). If you run multiple [Warp release channels](/support-and-community/community/warp-preview-and-alpha-program/), each channel has its own settings directory.

## Related pages

-   [All settings reference](/terminal/settings/all-settings/) — Complete list of every available setting with descriptions, types, and defaults
-   [Customizing Warp](/getting-started/quickstart/customizing-warp/) — Overview of all customization options
-   [Custom themes](/terminal/appearance/custom-themes/) — Create and load custom YAML or Base16 themes
-   [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) — Customize keybindings
-   [Settings Sync (Beta)](/terminal/more-features/settings-sync/) — Sync settings across machines