---
obj: application
repo: https://github.com/alacritty/alacritty
website: https://alacritty.org
---

# Alacritty
Alacritty is a modern terminal emulator that comes with sensible defaults, but allows for extensive configuration. By integrating with other applications, rather than reimplementing their functionality, it manages to provide a flexible set of features with high performance. The supported platforms currently consist of BSD, [Linux](../../linux/Linux.md), [macOS](../../macos/macOS.md) and [Windows](../../windows/Windows.md).

![Screenshot](./alacritty.avif)

## Configuration
Alacritty is highly customizable and can be configured using a [TOML](../../files/TOML.md) configuration file. Previous versions have used a [YAML](../../files/YAML.md) file. The configuration file is located in `~/.config/alacritty/alacritty.toml` on [Linux](../../linux/Linux.md) and [macOS](../../macos/macOS.md), and in `%APPDATA%\alacritty\alacritty.toml` on [Windows](../../windows/Windows.md).

Here is an example configuration file:
```yml
# This is an example Alacritty configuration file
[font]
family: Fira Code
size: 14.0

[colors]
[colors.primary]
background: '#1d1f21'
foreground: '#c5c8c6'

[colors.normal]
black:   '#282a2e'
red:     '#a54242'
green:   '#8c9440'
yellow:  '#de935f'
blue:    '#5f819d'
magenta: '#85678f'
cyan:    '#5e8d87'
white:   '#707880'
```

## Configuration Options
### General
This is the root level of the config file.

- `import = ["",]`: Import additional configuration files.

### Font
The `font` section allows you to set the font family and size used by Alacritty. You can set the font size to a decimal value, which can be helpful if you want to fine-tune the size.
```toml
[font]
family = "Fira Code"
size = 14.0
```

### Colors
The `colors` section allows you to set the color scheme used by Alacritty. There are three main categories of colors:

-   `primary`: The background and foreground colors of the terminal window itself.
-   `normal`: The colors used for regular text in the terminal.
-   `bright`: The colors used for bold text in the terminal.

Each category can have different colors for each of the eight ANSI color codes (black, red, green, yellow, blue, magenta, cyan, and white). You can set colors using HEX color codes or RGB values.
```toml
[colors]
[colors.primary]
background = '#1d1f21'
foreground = '#c5c8c6'

[colors.normal]
black = '#282a2e'
red = '#a54242'
green = '#8c9440'
yellow = '#de935f'
blue = '#5f819d'
magenta = '#85678f'
cyan = '#5e8d87'
white = '#707880'

[colors.bright]
black = '#373b41'
red = '#cc6666'
green = '#b5bd68'
yellow = '#f0c674'
blue = '#81a2be'
magenta = '#b294bb'
cyan = '#8abeb7'
white = '#c5c8c6'
```

### Working Directory
You can set the initial directory that your [shell](Shell.md) will start in when you launch Alacritty
```toml
# working_directory = None
working_directory = "/home/your-username"
```

### Shell
You can control the [shell](Shell.md) that Alacritty uses when you launch it. By default, Alacritty will use the user's login [shell](Shell.md) on [Linux](../../linux/Linux.md) and BSD systems, `/bin/bash --login` on [macOS](../../macos/macOS.md), and PowerShell on [Windows](../../windows/Windows.md)
```toml
[shell]
program = /bin/zsh
args = ["- --rcfile", "/path/to/your/zshrc"]
```

### Environment
The Alacritty configuration file allows you to set [environment variables](../../linux/Environment%20Variables.md) that will be available to your [shell](Shell.md) sessions. Any entries in the `env` section will be added as [environment variables](../../linux/Environment%20Variables.md) when Alacritty launches your [shell](Shell.md)
```toml
[env]
TERM = "alacritty"
EDITOR = "nano"
```

### Window
The `window` section of the Alacritty configuration file contains options related to the appearance and behavior of the terminal window itself.

- The `dimensions` option allows you to set the number of lines and columns that are displayed in the terminal. The default value of `0` will fall back to the window manager's recommended size.
- The `position` option lets you specify the position of the window on the screen in pixels. If this option is not set, the window manager will handle the placement.
- The `opacity` option sets the opacity of the terminal window as a floating point number from `0.0` to `1.0`, with `0.0` being completely transparent and `1.0` being opaque.
- The `startup_mode` option allows you to specify how the window should be displayed when Alacritty starts up. You can choose between `Windowed`, `Maximized`, and `Fullscreen`. On [macOS](../../macos/macOS.md), there is an additional option called `SimpleFullscreen`.
- The `title` option sets the title of the terminal window.
- The `dynamic_title` option allows terminal applications to change the title of the Alacritty window. When this option is set to `true`, the window title will be updated to match the title of the currently running program.
```toml
[window]
[window.dimensions]
columns = 100
lines = 40
    
[window.position]
x = 100
y = 100


# Background opacity
# Window opacity as a floating point number from `0.0` to `1.0`
[window]
opacity: 0.9 # Set the window opacity to 90%

# Startup Mode (changes require restart)
#
# Values for `startup_mode`:
#   - Windowed
#   - Maximized
#   - Fullscreen
#
# Values for `startup_mode` (macOS only):
#   - SimpleFullscreen
startup_mode: Maximized

title: "Alacritty"

dynamic_title: true
```
