Alacritty Terminal Configuration Guide

Preview

Alacritty Configuration Reference

This document serves as a complete reference manual for Alacritty's alacritty.toml configuration file.

Syntax

Alacritty's configuration file uses the TOML format. The format's specification can be found at https://toml.io/en/v1.0.0.

Location

Alacritty does not create the configuration file for you, but it looks for one in the following locations.

On UNIX systems:

1. $XDG_CONFIG_HOME/alacritty/alacritty.toml
2. $XDG_CONFIG_HOME/alacritty.toml
3. $HOME/.config/alacritty/alacritty.toml
4. $HOME/.alacritty.toml

On Windows:

1. %APPDATA%\alacritty\alacritty.toml

[general] - General Configuration

This section documents the [general] table of the configuration file.

import

• Format: ["<string>", ...]
• Description: Import additional configuration files. Imports are loaded in order, and if a field is already present, it will be replaced by the value from a later import. Paths must be absolute, relative to the user's home directory (~/), or relative to the config file's location.

working_directory

• Format: "<string>" or "None"
• Description: Specifies the directory the shell starts in. If set to "None", the working directory of the parent process is used.
• Default: "None"

live_config_reload

• Format: true | false
• Description: Enables or disables live config reload.
• Default: true

ipc_socket

• Format: true | false
• Description: Offers IPC (Inter-Process Communication) support via alacritty msg.
• Platform: Unix only.
• Default: true

[env] - Environment Variables

All key-value pairs in the [env] section will be added as environment variables for any process spawned by Alacritty, including its shell.

• Example:

  toml
  [env]
  WINIT_X11_SCALE_FACTOR = "1.0"
  

[window] - Window Configuration

This section documents the [window] table of the configuration file.

dimensions

• Format: { columns = <integer>, lines = <integer> }
• Description: Defines the window dimensions in lines and columns. Both values must be non-zero to take effect, and columns must be at least 2. Changes require a restart.
• Default: { columns = 0, lines = 0 }

position

• Format: { x = <integer>, y = <integer> } or "None"
• Description: Sets the window's startup position in pixels. If set to "None", the window manager will handle placement.
• Platform: Has no effect on Wayland.
• Default: "None"

padding

• Format: { x = <integer>, y = <integer> }
• Description: Adds blank space around the window in pixels, scaled by DPI.
• Default: { x = 0, y = 0 }

dynamic_padding

• Format: true | false
• Description: Spreads additional padding evenly around the terminal content when the window is not a multiple of the cell size.
• Default: false

decorations

• Format: "Full" | "None" | "Transparent" | "Buttonless"
• Description: Controls the window decorations.
  • Full: Includes borders and a title bar.
  • None: Has neither borders nor a title bar.
  • Transparent (macOS only): Provides a title bar with a transparent background.
  • Buttonless (macOS only): Similar to Transparent but without title bar buttons.
• Default: "Full"

opacity

• Format: <float>
• Description: Sets the background opacity from 0.0 (completely transparent) to 1.0 (opaque).
• Default: 1.0

blur

• Format: true | false
• Description: Requests that the compositor blur content behind transparent windows.
• Platform: Works on macOS and KDE Wayland.
• Default: false

startup_mode

• Format: "Windowed" | "Maximized" | "Fullscreen" | "SimpleFullscreen"
• Description: Defines the window mode on startup. Changes require a restart.
  • Windowed: Starts as a regular window.
  • Maximized: Starts maximized.
  • Fullscreen: Starts in fullscreen mode.
  • SimpleFullscreen (macOS only): A form of fullscreen that allows other windows to be stacked on top.
• Default: "Windowed"

title

• Format: "<string>"
• Description: Sets the window's title.
• Default: "Alacritty"

dynamic_title

• Format: true | false
• Description: Allows terminal applications to change the window's title.
• Default: true

class

• Format: { instance = "<string>", general = "<string>" }
• Description: Sets the window class. On Wayland, general is used as the app_id.
• Platform: Linux/BSD only.
• Default: { instance = "Alacritty", general = "Alacritty" }

decorations_theme_variant

• Format: "Dark" | "Light" | "None"
• Description: Overrides the system's theme variant for window decorations. "None" uses the system default.
• Default: "None"

resize_increments

• Format: true | false
• Description: When enabled, the window resizes in discrete steps equal to cell dimensions.
• Platform: Works on macOS/X11.
• Default: false

option_as_alt

• Format: "OnlyLeft" | "OnlyRight" | "Both" | "None"
• Description: Configures the Option key to behave as Alt.
• Platform: macOS only.
• Default: "None"

level

• Format: "Normal" | "AlwaysOnTop"
• Description: Sets the window's z-order level. AlwaysOnTop keeps the window as a toplevel window.
• Default: "Normal"

[scrolling] - Scrolling Configuration

This section documents the [scrolling] table of the configuration file.

history

• Format: <integer>
• Description: Sets the maximum number of lines in the scrollback buffer. A value of 0 disables scrolling. The value is limited to 100000.
• Default: 10000

multiplier

• Format: <integer>
• Description: The number of lines to scroll for each scroll input increment.
• Default: 3

[font] - Font Configuration

This section documents the [font] table of the configuration file.

normal

• Format: { family = "<string>", style = "<string>" }
• Description: The font for normal text.
• Default: Varies by OS: monospace on Linux/BSD, Consolas on Windows, and Menlo on macOS.

bold

• Format: { family = "<string>", style = "<string>" }
• Description: The font for bold text. If family is not specified, it falls back to the normal font's family.
• Default: { style = "Bold" }

italic

• Format: { family = "<string>", style = "<string>" }
• Description: The font for italic text. If family is not specified, it falls back to the normal font's family.
• Default: { style = "Italic" }

bold_italic

• Format: { family = "<string>", style = "<string>" }
• Description: The font for bold italic text. If family is not specified, it falls back to the normal font's family.
• Default: { style = "Bold Italic" }

size

• Format: <float>
• Description: Font size in points.
• Default: 11.25

offset

• Format: { x = <integer>, y = <integer> }
• Description: Extra space around each character. y modifies line spacing, and x modifies letter spacing.
• Default: { x = 0, y = 0 }

glyph_offset

• Format: { x = <integer>, y = <integer> }
• Description: Determines the location of glyphs within their cells. Increasing x moves the glyph right, and increasing y moves it upward.

builtin_box_drawing

• Format: true | false
• Description: If true, Alacritty uses a custom built-in font for box drawing characters, legacy computing symbols, and powerline symbols.
• Default: true

[colors] - Color Configuration

This section documents the [colors] table. Colors are specified using hexadecimal values with a # prefix (e.g., #RRGGBB).

primary

• Description: Defines the primary color palette.
  • foreground: Default is "#d8d8d8".
  • background: Default is "#181818".
  • dim_foreground: Default is "#828482". If not set, it is automatically calculated from the foreground color.
  • bright_foreground: Default is None. Only used when draw_bold_text_with_bright_colors is true.

cursor

• Format: { text = "<string>", cursor = "<string>" }
• Description: Colors for the terminal cursor. Allowed values are hex colors or CellForeground/CellBackground.
• Default: { text = "CellBackground", cursor = "CellForeground" }

vi_mode_cursor

• Format: { text = "<string>", cursor = "<string>" }
• Description: Colors for the cursor when vi mode is active.
• Default: { text = "CellBackground", cursor = "CellForeground" }

selection

• Format: { text = "<string>", background = "<string>" }
• Description: Colors used for drawing text selections.
• Default: { text = "CellBackground", background = "CellForeground" }

normal

• Description: The 8 normal terminal colors.
  • black: "#181818"
  • red: "#ac4242"
  • green: "#90a959"
  • yellow: "#f4bf75"
  • blue: "#6a9fb5"
  • magenta: "#aa759f"
  • cyan: "#75b5aa"
  • white: "#d8d8d8"

bright

• Description: The 8 bright terminal colors.
  • black: "#6b6b6b"
  • red: "#c55555"
  • green: "#aac474"
  • yellow: "#feca88"
  • blue: "#82b8c8"
  • magenta: "#c28cb8"
  • cyan: "#93d3c3"
  • white: "#f8f8f8"

draw_bold_text_with_bright_colors

• Format: true | false
• Description: If true, bold text is drawn using the bright color variants.
• Default: false

[keyboard] - Keyboard Configuration

This section documents the [keyboard] table.

bindings

• Format: [{ key = "<key>", mods = "<mods>", action = "<action>" | ... }, ...]
• Description: Defines an array of key bindings. To unset a default binding, use the action "ReceiveChar" or "None".
• Fields:
  • key: The key name (e.g., "A", "F1") or a decimal scancode.
  • mods: Modifiers like "Control", "Shift", "Alt", which can be combined with |.
  • mode: A terminal mode that must be active for the binding to trigger (e.g., "Vi", "Search").
  • action: A predefined action, such as Copy, Paste, or ToggleFullscreen.
  • chars: A string to write to the terminal.
  • command: A command to execute.

References

• Official Documentation
• Download Link
• Rust Documentation