Alacritty Configuration

Alacritty configuration yaml file

Type object
File match .alacritty.yml alacritty.yml alacritty.toml
Schema URL https://catalog.lintel.tools/schemas/schemastore/alacritty-configuration/latest.json
Source https://raw.githubusercontent.com/distinction-dev/alacritty-schema/main/alacritty/reference.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Configuration schema for Alacritty, the GPU enhanced terminal emulator

Properties

import string[]

Import additional configuration files. Imports are loaded in order, skipping all missing files, with the importing file being loaded last. If a field is already present in a previous import, it will be replaced.

shell string | object

You can set shell.program to the path of your favorite shell, e.g. /bin/zsh. Entries in shell.args are passed as arguments to the shell

working_directory string

Startup directory

Directory the shell is started in. If this is unset, or None, the working directory of the parent process will be used.

Default: "None"
live_config_reload boolean

Live config reload (changes require restart). Will make alacritty auto load new changes in the config file

ipc_socket boolean

Offer IPC using alacritty msg (unix only)

env object

Any items in the env entry below will be added as environment variables. Some entries may override variables set by alacritty itself.

window object
14 nested properties
dimensions object

Window dimensions (changes require restart). Number of lines/columns (not pixels) in the terminal. Both lines and columns must be non-zero for this to take effect. The number of columns must be at least 2, while using a value of 0 for columns and lines will fall back to the window manager's recommended size

2 nested properties
columns number
min=2
lines number
min=0
position object

Window position (changes require restart) Specified in number of pixels. If the position is not set, the window manager will handle the placement.

2 nested properties
x number
y number
padding object

Window padding (changes require restart)

Blank space added around the window in pixels. This padding is scaled by DPI and the specified value is always added at both opposing sides.

2 nested properties
x number
y number
dynamic_padding boolean

Spread additional padding evenly around the terminal content.

decorations string

Values for decorations: - full: Borders and title bar - none: Neither borders nor title bar

Values for decorations (macOS only): - transparent: Title bar, transparent background and title bar buttons - buttonless: Title bar, transparent background and no title bar buttons

Values: "full" "none" "transparent" "buttonless"
opacity number

Background opacity

Window opacity as a floating point number from 0.0 to 1.0. The value 0.0 is completely transparent and 1.0 is opaque.

Default: 1.0
min=0max=1
blur boolean

Request compositor to blur content behind transparent windows

Default: "false"
startup_mode string

Startup Mode (changes require restart)

Values for startup_mode:

  • Windowed
  • Maximized
  • Fullscreen

Values for startup_mode (macOS only):

  • SimpleFullscreen
Values: "Windowed" "Maximized" "Fullscreen" "SimpleFullscreen"
title string

Window Title

dynamic_title boolean

Allow terminal applications to change Alacritty's window title.

Default: true
class object

Window class (Linux/BSD only):

2 nested properties
instance string
Default: "Alacritty"
general string
Default: "Alacritty"
decorations_theme_variant string

Decorations theme variant (Linux/BSD only)

Override the variant of the GTK theme/Wayland client side decorations. Commonly supported values are dark and light. Set this to None to use the default theme variant.

Default: "None"
resize_increments boolean

Prefer resizing window by discrete steps equal to cell dimensions

Default: "false"
option_as_alt string

Make Option key behave as Alt (macos only)

Default: "None"
Values: "OnlyLeft" "OnlyRight" "Both" "None"
scrolling object
2 nested properties
history integer

Maximum number of lines in the scrollback buffer. Specifying '0' will disable scrolling.

Default: 10000
min=0
multiplier integer

Scrolling distance multiplier.

Default: 3
font object
8 nested properties
normal object
2 nested properties
family string

Font family

Default:

  • (macOS) Menlo
  • (Linux/BSD) monospace
  • (Windows) Consolas
style string

The style can be specified to pick a specific face.

bold object
2 nested properties
family string

If the bold family is not specified, it will fall back to the value specified for the normal font.

style string

The style can be specified to pick a specific face.

italic object
2 nested properties
family string

If the italic family is not specified, it will fall back to the value specified for the normal font.

style string

The style can be specified to pick a specific face.

bold_italic object
2 nested properties
family string

If the bold_italic family is not specified, it will fall back to the value specified for the normal font.

style string

The style can be specified to pick a specific face.

size number

Point size

min=0
offset object

Offset is the extra space around each character. offset.y can be thought of as modifying the line spacing, and offset.x as modifying the letter spacing.

2 nested properties
x number
Default: 0
y number
Default: 0
glyph_offset object

Glyph offset determines the locations of the glyphs within their cells with the default being at the bottom. Increasing x moves the glyph to the right, increasing y moves the glyph upward.

2 nested properties
x number
Default: 0
y number
Default: 0
builtin_box_drawing boolean

Use built-in font for box drawing characters.

If true, Alacritty will use a custom built-in font for box drawing characters (Unicode points 2500 - 259f).

Default: false
colors object
14 nested properties
primary object
4 nested properties
foreground string
Default: "#d8d8d8"
pattern=#[a-z0-9]{6}
background string
Default: "#181818"
pattern=#[a-z0-9]{6}
dim_foreground string

If this is not set, the color is automatically calculated based on the foreground color

Default: "#828482"
pattern=#[a-z0-9]{6}
bright_foreground string

This color is only used when draw_bold_text_with_bright_colors is true. If this is not set, the normal foreground will be used

Default: "None"
pattern=#[a-z0-9]{6}|None
cursor object

Colors which should be used to draw the terminal cursor. Allowed values are hexadecimal colors like #ff00ff, or CellForeground/CellBackground, which references the affected cell

2 nested properties
text string
Default: "CellBackground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
cursor string
Default: "CellForeground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
vi_mode_cursor object

Colors for the cursor when the vi mode is active. Allowed values are hexadecimal colors like #ff00ff, or CellForeground/CellBackground, which references the affected cell

2 nested properties
text string
Default: "CellBackground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
cursor string
Default: "CellForeground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
search object
2 nested properties
matches object
2 nested properties
foreground string
Default: "#181818"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
background string
Default: "#ac4242"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
focused_match object
2 nested properties
foreground string
Default: "#181818"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
background string
Default: "#f4bf75"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
hints object
2 nested properties
start object

First character in the hint label. Allowed values are hexadecimal colors like #ff00ff, or CellForeground/CellBackground, which references the affected cell

2 nested properties
foreground string
Default: "#181818"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
background string
Default: "#f4bf75"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
end object

All characters after the first one in the hint label. Allowed values are hexadecimal colors like #ff00ff, or CellForeground/CellBackground, which references the affected cell

2 nested properties
foreground string
Default: "#181818"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
background string
Default: "#ac4242"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
line_indicator object

Color used for the indicator displaying the position in history during search and vi mode

2 nested properties
foreground string
Default: "None"
pattern=#[a-z0-9]{6}|None
background string
Default: "None"
pattern=#[a-z0-9]{6}|None
footer_bar object

Color used for the footer bar on the bottom, used by search regex input, hyperlink URI preview, etc

2 nested properties
foreground string
Default: "#181818"
pattern=#[a-z0-9]{6}
background string
Default: "#d8d8d8"
pattern=#[a-z0-9]{6}
selection object

Colors used for drawing selections. Allowed values are hexadecimal colors like #ff00ff, or CellForeground/CellBackground, which references the affected cell

2 nested properties
text string
Default: "CellBackground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
cursor string
Default: "CellForeground"
pattern=#[a-z0-9]{6}|CellBackground|CellForeground
normal object
8 nested properties
black string
Default: "#181818"
pattern=#[a-z0-9]{6}
red string
Default: "#ac4242"
pattern=#[a-z0-9]{6}
green string
Default: "#90a959"
pattern=#[a-z0-9]{6}
yellow string
Default: "#f4bf75"
pattern=#[a-z0-9]{6}
blue string
Default: "#689fb5"
pattern=#[a-z0-9]{6}
magenta string
Default: "#aa759f"
pattern=#[a-z0-9]{6}
cyan string
Default: "#75b5aa"
pattern=#[a-z0-9]{6}
white string
Default: "#d8d8d8"
pattern=#[a-z0-9]{6}
bright object
8 nested properties
black string
Default: "#6b6b6b"
pattern=#[a-z0-9]{6}
red string
Default: "#c55555"
pattern=#[a-z0-9]{6}
green string
Default: "#aac474"
pattern=#[a-z0-9]{6}
yellow string
Default: "#feca88"
pattern=#[a-z0-9]{6}
blue string
Default: "#82b8c8"
pattern=#[a-z0-9]{6}
magenta string
Default: "#c28cb8"
pattern=#[a-z0-9]{6}
cyan string
Default: "#93d3c3"
pattern=#[a-z0-9]{6}
white string
Default: "#f8f8f8"
pattern=#[a-z0-9]{6}
dim object
8 nested properties
black string
Default: "#0f0f0f"
pattern=#[a-z0-9]{6}
red string
Default: "#712b2b"
pattern=#[a-z0-9]{6}
green string
Default: "#5f6f3a"
pattern=#[a-z0-9]{6}
yellow string
Default: "#a17e4d"
pattern=#[a-z0-9]{6}
blue string
Default: "#456877"
pattern=#[a-z0-9]{6}
magenta string
Default: "#704d68"
pattern=#[a-z0-9]{6}
cyan string
Default: "#4d7770"
pattern=#[a-z0-9]{6}
white string
Default: "#8e8e8e"
pattern=#[a-z0-9]{6}
indexed_colors object[]

The indexed colors include all colors from 16 to 256. When these are not set, they're filled with sensible defaults

transparent_background_colors boolean

Whether or not window.opacity applies to all cell backgrounds, or only to the default background. When set to true all cells will be transparent regardless of their background color

Default: "false"
draw_bold_text_with_bright_colors boolean

If true, bold text is drawn using the bright color variants.

Default: "false"
bell object

The bell is rung every time the BEL control character is received.

4 nested properties
animation string

Animation effect for flashing the screen when the visual bell is rung.

Default: "Linear"
Values: "Ease" "EaseOut" "EaseOutSine" "EaseOutQuad" "EaseOutCubic" "EaseOutQuart" "EaseOutQuint" "EaseOutExpo" "EaseOutCirc" "Linear"
duration integer

Duration of the visual bell flash in milliseconds. A duration of 0 will disable the visual bell animation.

Default: 0
color string

Visual bell animation color.

Default: "#ffffff"
pattern=#[a-z0-9]{6}
command object
2 nested properties
program string
args string[]
selection object
2 nested properties
semantic_escape_chars string

This string contains all characters that are used as separators for "semantic words" in Alacritty.

Default: ",│`|:"' ()[]{}<> "
save_to_clipboard boolean

When set to true, selected text will be copied to the primary clipboard.

Default: false
cursor object
6 nested properties
style object

Cursor Style

2 nested properties
shape string

Cursor shape

Values for shape:

  • ▇ Block
  • _ Underline
  • | Beam
Default: "Block"
Values: "Block" "Beam" "Underline"
blinking string

Cursor blinking state

Values for blinking:

  • Never: Prevent the cursor from ever blinking
  • Off: Disable blinking by default
  • On: Enable blinking by default
  • Always: Force the cursor to always blink
Default: "Off"
Values: "Never" "Off" "On" "Always"
vi_mode_style Alacritty.Cursor.Style | string

Vi mode cursor style If the vi mode cursor style is None or not specified, it will fall back to the style of the active value of the normal cursor.

blink_interval integer

Cursor blinking interval in milliseconds.

Default: 750
min=0
blink_timeout integer

Time after which cursor stops blinking in seconds.

Specifying '0' will disable timeout for blinking

Default: 5
unfocused_hollow boolean

If this is true, the cursor will be rendered as a hollow box when the window is not focused.

Default: true
thickness number

Thickness of the cursor relative to the cell width as floating point number from 0.0 to 1.0.

min=0max=1
terminal object
mouse object
2 nested properties
hide_when_typing boolean

When this is true, the cursor is temporarily hidden when typing.

Default: false
bindings Alacritty.MouseBinding[]
hints object

Terminal hints can be used to find text or hyperlinks in the visible part of the terminal and pipe it to other applications

2 nested properties
alphabet string

Keys used for the hint labels

Default: "jfkdls;ahgurieowpq"
enabled object[]

Array with all available hints. Each hint must have at least one of regex or hyperlinks and either an action or a command

key
1 nested properties
bindings object[]
debug object
7 nested properties
render_timer boolean

Display the time it takes to redraw each frame.

Default: false
persistent_logging boolean

Keep the log file after quitting Alacritty.

Default: false
log_level string

To add extra libraries to logging ALACRITTY_EXTRA_LOG_TARGETS variable can be used

Default: "Warn"
Values: "Off" "Error" "Warn" "Info" "Debug" "Trace"
renderer string

Force use of a specific renderer, "None" will use the highest available one.

Default: "None"
Values: "glsl3" "gles2" "gles2_pure" "None"
print_events boolean

Log all received window events

Default: false
highlight_damage boolean

Highlight window damage information.

Default: false
prefer_egl boolean

Use EGL as display API if the current platform allows it. Note that transparency may not work with EGL on Linux/BSD

Default: false

Definitions

Alacritty.Cursor.Style object

Cursor Style

shape string

Cursor shape

Values for shape:

  • ▇ Block
  • _ Underline
  • | Beam
Default: "Block"
Values: "Block" "Beam" "Underline"
blinking string

Cursor blinking state

Values for blinking:

  • Never: Prevent the cursor from ever blinking
  • Off: Disable blinking by default
  • On: Enable blinking by default
  • Always: Force the cursor to always blink
Default: "Off"
Values: "Never" "Off" "On" "Always"
Alacritty.Command object
program string
args string[]
Alacritty.MouseBinding object
mouse string required
Values: "Left" "Middle" "Right"
action string required
Alacritty.KeyBindings.Key string

Identifier of the key pressed.

  • A-Z
  • F1-F24
  • Key0-Key9

A full list with available key codes can be found here: https://docs.rs/glutin/*/glutin/event/enum.VirtualKeyCode.html#variants

Instead of using the name of the keys, the key field also supports using the scancode of the desired key. Scancodes have to be specified as a decimal number. This command will allow you to display the hex scancodes for certain keys:

`showkey --scancodes`.
Alacritty.KeyBindings.Chars string

The chars field writes the specified string to the terminal. This makes it possible to pass escape sequences. To find escape codes for bindings like PageUp ("\x1b[5~"), you can run the command showkey -a outside of tmux. Note that applications use terminfo to map escape sequences back to keys. It is therefore required to update the terminfo when changing an escape sequence.

Alacritty.KeyBindings.Action string

Execute a predefined action

  • ToggleViMode
  • SearchForward Start searching toward the right of the search origin.
  • SearchBackward Start searching toward the left of the search origin.
  • Copy
  • Paste
  • IncreaseFontSize
  • DecreaseFontSize
  • ResetFontSize
  • ScrollPageUp
  • ScrollPageDown
  • ScrollHalfPageUp
  • ScrollHalfPageDown
  • ScrollLineUp
  • ScrollLineDown
  • ScrollToTop
  • ScrollToBottom
  • ClearHistory Remove the terminal's scrollback history.
  • Hide Hide the Alacritty window.
  • Minimize Minimize the Alacritty window.
  • Quit Quit Alacritty.
  • ToggleFullscreen
  • SpawnNewInstance Spawn a new instance of Alacritty.
  • CreateNewWindow Create a new Alacritty window from the current process.
  • ClearLogNotice Clear Alacritty's UI warning and error notice.
  • ClearSelection Remove the active selection.
  • ReceiveChar
  • None
  • Vi mode exclusive actions:
    • Open Perform the action of the first matching hint under the vi mode cursor with mouse.enabled set to true.
    • ToggleNormalSelection
    • ToggleLineSelection
    • ToggleBlockSelection
    • ToggleSemanticSelection Toggle semantic selection based on selection.semantic_escape_chars.
    • CenterAroundViCursor Center view around vi mode cursor
  • Vi mode exclusive cursor motion actions:
    • Up One line up.
    • Down One line down.
    • Left One character left.
    • Right One character right.
    • First First column, or beginning of the line when already at the first column.
    • Last Last column, or beginning of the line when already at the last column.
    • FirstOccupied First non-empty cell in this terminal row, or first non-empty cell of the line when already at the first cell of the row.
    • High Top of the screen.
    • Middle Center of the screen.
    • Low Bottom of the screen.
    • SemanticLeft Start of the previous semantically separated word.
    • SemanticRight Start of the next semantically separated word.
    • SemanticLeftEnd End of the previous semantically separated word.
    • SemanticRightEnd End of the next semantically separated word.
    • WordLeft Start of the previous whitespace separated word.
    • WordRight Start of the next whitespace separated word.
    • WordLeftEnd End of the previous whitespace separated word.
    • WordRightEnd End of the next whitespace separated word.
    • Bracket Character matching the bracket at the cursor's location.
    • SearchNext Beginning of the next match.
    • SearchPrevious Beginning of the previous match.
    • SearchStart Start of the match to the left of the vi mode cursor.
    • SearchEnd End of the match to the right of the vi mode cursor.
  • Search mode exclusive actions:
    • SearchFocusNext Move the focus to the next search match.
    • SearchFocusPrevious Move the focus to the previous search match.
    • SearchConfirm
    • SearchCancel
    • SearchClear Reset the search regex.
    • SearchDeleteWord Delete the last word in the search regex.
    • SearchHistoryPrevious Go to the previous regex in the search history.
    • SearchHistoryNext Go to the next regex in the search history.
  • macOS exclusive actions:
    • ToggleSimpleFullscreen Enter fullscreen without occupying another space.
  • Linux/BSD exclusive actions:
    • CopySelection Copy from the selection buffer.
    • PasteSelection Paste from the selection buffer.
Alacritty.Mode string
Alacritty.Mods string

Multiple modifiers can be combined using |, like this: "Control | Shift"