Alacritty Terminal Configuration Guide

Introduction

Alacritty is a contemporary terminal emulator, characterized by sensible defaults yet allowing for extensive customization. By integrating with other applications, rather than reimplementing their functionalities, it offers a flexible and high-performance feature set. The currently supported platforms encompass BSD, Linux, macOS, and Windows.

Installation

If modification of the icon is not required, direct download is recommended:

• Directly download the officially compiled installation package: https://alacritty.org/index.html

• Manual Compilation Here, because the source code's icon is square with right angles and does not quite align with the macOS icon style, I have personally forked a version with a modified icon, thus necessitating manual compilation.

Install the Rust and Make environments:

bash
# Install the Rust environment; if it already exists, this step can be skipped.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

brew install make

bash
 # Shallow clone the repository code.
git clone --depth 1 https://github.com/KevinYouu/alacritty.git

cd alacritty

# Compile for the current architecture.
make dmg

# Compile the universal architecture for macOS.
# dmg-universal

Subsequently, the compiled application and DMG file can be located in the alacritty/target/release/osx directory. Simply place these into /Applications for immediate use.

Configuration

The following is my personalized configuration file:

toml
[window]
dimensions = { columns = 80, lines = 24 }
padding = { x = 4, y = 0 }
opacity = 0.2
blur = true

[font]
normal = { family = "Roboto Mono", style = "Regular" }
bold = { family = "Roboto Mono", style = "bold" }
italic = { family = "Roboto Mono", style = "italic" }
bold_italic = { family = "Roboto Mono", style = "bold italic" }
size = 18

[selection]
save_to_clipboard = true
semantic_escape_chars = ",│`|:\"' ()[]{}<>\t"

[cursor]
style = { shape = "Beam", blinking = "On" }

[terminal]
shell = { program = "/opt/homebrew/bin/fish", args = ["-l"] }

[colors.primary]
foreground = "#ffffff" # White
background = "#000000" # Black

[colors.normal]
black = "#000000"
red = "#ff3b30"
green = "#4cd964"
yellow = "#ffcc00"
blue = "#007aff"
magenta = "#ff2d55"
cyan = "#5ac8fa"
white = "#ffffff"

[colors.bright]
black = "#686868"
red = "#ff3b30"
green = "#4cd964"
yellow = "#ffcc00"
blue = "#007aff"
magenta = "#ff2d55"
cyan = "#5ac8fa"
white = "#ffffff"

[keyboard]
bindings = [
    # Copy (Cmd + C)
    { key = "C", mods = "Command", action = "Copy" },

    # Paste (Cmd + V)
    { key = "V", mods = "Command", action = "Paste" },

    # Find (Cmd + F)
    { key = "F", mods = "Command", action = "SearchForward" },

    # New Window (Cmd + N)
    { key = "N", mods = "Command", action = "CreateNewWindow" },

    # Decrease Font Size (Cmd + -)
    { key = "Minus", mods = "Command", action = "DecreaseFontSize" },

    # Increase Font Size (Cmd + =)
    { key = "Equals", mods = "Command", action = "IncreaseFontSize" },

    # Reset Font Size (Cmd + 0)
    { key = "Key0", mods = "Command", action = "ResetFontSize" },

    # Toggle Full Screen (Cmd + Enter)
    { key = "Return", mods = "Command", action = "ToggleSimpleFullscreen" },

    # Switch to Specific Tab (Cmd + 1 ~ Cmd + 9)
    { key = "Key1", mods = "Command", action = "SelectTab1" },
    { key = "Key2", mods = "Command", action = "SelectTab2" },
    { key = "Key3", mods = "Command", action = "SelectTab3" },
    { key = "Key4", mods = "Command", action = "SelectTab4" },
    { key = "Key5", mods = "Command", action = "SelectTab5" },
    { key = "Key6", mods = "Command", action = "SelectTab6" },
    { key = "Key7", mods = "Command", action = "SelectTab7" },
    { key = "Key8", mods = "Command", action = "SelectTab8" },
    { key = "Key9", mods = "Command", action = "SelectTab9" },

    # Hide Alacritty (Cmd + H)
    { key = "H", mods = "Command", action = "Hide" },

    # Hide Other Applications (Cmd + Option + H)
    { key = "H", mods = "Command|Option", action = "HideOtherApplications" },
]

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