Configure Alacritty for Daily Use

Alacritty is a GPU-accelerated terminal emulator that deliberately keeps its feature set small and its configuration transparent. Everything lives in a single alacritty.toml file, which means tweaking fonts, colours, or key bindings is a text-editor job rather than a menu hunt. This guide walks through a practical daily-driver setup: readable theme, ligature-capable font, useful key bindings, and an automatic tmux session on launch.

Install Alacritty

Debian / Ubuntu

sudo apt install alacritty

Ubuntu 22.04 LTS ships Alacritty 0.10; Ubuntu 24.04 LTS ships 0.13. On 22.04 consider the upstream PPA or a Cargo build for TOML config support (TOML replaced YAML in 0.12).

Fedora / RHEL family

sudo dnf install alacritty

Arch

sudo pacman -S alacritty

Verify the version before continuing — the alacritty.toml format requires 0.12 or later.

alacritty --version

Create the Configuration File

Alacritty follows the XDG Base Directory spec. Create the config directory and an empty file:

mkdir -p ~/.config/alacritty
touch ~/.config/alacritty/alacritty.toml

Alacritty hot-reloads the file on save, so you can keep it open in your editor and see changes immediately.

Set a Theme

The cleanest way to manage themes is to keep them in a separate file and import it. The community alacritty-theme repository has ready-made TOML files for over 200 colour schemes.

mkdir -p ~/.config/alacritty/themes
git clone https://github.com/alacritty/alacritty-theme ~/.config/alacritty/themes

Add an import block at the top of alacritty.toml. This example uses the popular Tokyo Night scheme; swap the filename for any file inside themes/themes/:

cat >> ~/.config/alacritty/alacritty.toml << 'EOF'
import = [
  "~/.config/alacritty/themes/themes/tokyo_night.toml"
]
EOF

To preview other schemes without restarting, edit the import line and save — the terminal repaints in under a second.

Configure the Font

Alacritty renders whatever font your system provides, but for ligatures you need a font that includes ligature glyphs and you need to enable them. Good free choices: Fira Code, JetBrains Mono, Cascadia Code.

Install a Nerd Font variant (optional but useful for Powerline/nvim)

# Debian/Ubuntu — nerd-fonts packages are in the repos on 24.04+
sudo apt install fonts-firacode

# Fedora
sudo dnf install fira-code-fonts

# Arch (AUR helper needed for nerd-fonts; base package in extra)
sudo pacman -S ttf-firacode-nerd

Add the font section to alacritty.toml. Open the file in your editor and append:

[font]
normal = { family = "FiraCode Nerd Font", style = "Regular" }
bold   = { family = "FiraCode Nerd Font", style = "Bold" }
italic = { family = "FiraCode Nerd Font", style = "Light" }
size   = 13.0

[font.builtin_box_drawing]
enabled = true

Ligatures in Alacritty are enabled by default as of 0.13 — the renderer passes them through OpenType. If you are on an older build and see literal -> instead of an arrow, upgrade to 0.13+ or build from source; there is no config knob to force ligatures in earlier releases.

Tune Window and Scrollback

[window]
padding      = { x = 8, y = 6 }
decorations  = "full"      # "none" for borderless on tiling WMs
opacity      = 1.0         # 0.0–1.0; compositor required for < 1.0
dynamic_title = true

[scrolling]
history    = 10000
multiplier = 5             # lines scrolled per wheel tick

On Wayland, decorations = "none" relies on your compositor (Sway, Hyprland, GNOME Mutter) for window chrome. On X11 it produces a truly borderless window.

Define Key Bindings

Alacritty's default bindings are minimal. The [keyboard] table (renamed from [key_bindings] in 0.13) lets you add or override shortcuts. Each entry needs an action or a chars string to send.

[keyboard]
bindings = [
  # Increase/decrease font size without restarting
  { key = "Equals",    mods = "Control",       action = "IncreaseFontSize" },
  { key = "Minus",     mods = "Control",       action = "DecreaseFontSize" },
  { key = "Key0",      mods = "Control",       action = "ResetFontSize"    },

  # Copy / paste with Ctrl-Shift (leaves Ctrl-C for signals)
  { key = "C",         mods = "Control|Shift", action = "Copy"  },
  { key = "V",         mods = "Control|Shift", action = "Paste" },

  # Open a new Alacritty window
  { key = "N",         mods = "Control|Shift", action = "CreateNewWindow" },

  # Send Escape when pressing Caps Lock (map at OS level or use this workaround)
  # { key = "CapsLock", mods = "", chars = "\x1b" },
]

A full list of valid action values is in the official config reference. The chars field accepts escaped byte sequences, which is how you send arbitrary escape codes to applications.

Launch into a tmux Session Automatically

The [terminal] table lets you specify a shell command. The trick below attaches to a session named main if it exists, or creates it if it does not. This means every new Alacritty window drops you straight into a persistent tmux session.

[terminal]
shell = { program = "/bin/bash", args = ["-c", "tmux new-session -A -s main"] }

If you use fish or zsh, replace /bin/bash accordingly:

[terminal]
shell = { program = "/usr/bin/zsh", args = ["-c", "tmux new-session -A -s main"] }

Make sure tmux is installed first:

# Debian/Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

If you want different windows to attach to different sessions, create a wrapper script and point shell.program at it instead.

Verify the Configuration

Alacritty validates the config on load. To check for errors without opening a window:

alacritty msg config 2>&1 || alacritty --print-events 2>&1 | head -20

A cleaner method — check the journal if something silently fails:

journalctl --user -xe | grep -i alacritty

You can also run Alacritty with verbose logging to stdout:

WINIT_UNIX_BACKEND=x11 alacritty -vvv 2>&1 | head -40

Troubleshooting

Config changes have no effect

Check that you are editing the right file. Alacritty also looks in $ALACRITTY_CONFIG and (legacy) ~/.alacritty.toml. Run alacritty -vvv to see which path it loaded.

Garbled or missing glyphs

The font family name in the config must match exactly what fc-list | grep -i fira reports. Spacing and capitalisation matter. Use fc-match "FiraCode Nerd Font" to confirm the system resolves the name correctly.

tmux session not starting

If tmux is not on your PATH when the login environment is sourced, specify the full path: /usr/bin/tmux. Verify with which tmux. Also ensure your shell's rc file does not unconditionally start another tmux inside itself, or you will get infinite nesting.

Opacity / blur not working on Wayland

Compositors handle transparency differently. On Sway, add for_window [app_id="Alacritty"] opacity 0.95 to ~/.config/sway/config. On Hyprland, use the decoration block. GNOME on Wayland requires an extension (e.g., Blur my Shell) for blur; straight opacity via alacritty.toml works without extras.