1# Cargo Installation 2 3If you're just interested in the Alacritty binary and you don't need the 4[terminfo file](#terminfo), [desktop entry](#desktop-entry), 5[manual page](#manual-page) or [shell completions](#shell-completions), you can 6install it directly through cargo: 7 8```sh 9cargo install alacritty 10``` 11 12# Manual Installation 13 141. [Prerequisites](#prerequisites) 15 1. [Source Code](#clone-the-source-code) 16 2. [Rust Compiler](#install-the-rust-compiler-with-rustup) 17 3. [Dependencies](#dependencies) 18 1. [Debian/Ubuntu](#debianubuntu) 19 2. [Arch Linux](#arch-linux) 20 3. [Fedora](#fedora) 21 4. [CentOS/RHEL 7](#centosrhel-7) 22 5. [openSUSE](#opensuse) 23 6. [Slackware](#slackware) 24 7. [Void Linux](#void-linux) 25 8. [FreeBSD](#freebsd) 26 9. [OpenBSD](#openbsd) 27 10. [Solus](#solus) 28 11. [NixOS/Nixpkgs](#nixosnixpkgs) 29 12. [Gentoo](#gentoo) 30 13. [Clear Linux](#clear-linux) 31 14. [GNU Guix](#gnu-guix) 32 15. [Alpine Linux](#alpine-linux) 33 16. [Windows](#windows) 34 17. [Other](#other) 352. [Building](#building) 36 1. [Linux/Windows](#linux--windows) 37 2. [macOS](#macos) 383. [Post Build](#post-build) 39 1. [Terminfo](#terminfo) 40 2. [Desktop Entry](#desktop-entry) 41 3. [Manual Page](#manual-page) 42 4. [Shell completions](#shell-completions) 43 1. [Zsh](#zsh) 44 2. [Bash](#bash) 45 3. [Fish](#fish) 46 47## Prerequisites 48 49### Clone the source code 50 51Before compiling Alacritty, you'll have to first clone the source code: 52 53```sh 54git clone https://github.com/alacritty/alacritty.git 55cd alacritty 56``` 57 58### Install the Rust compiler with `rustup` 59 601. Install [`rustup.rs`](https://rustup.rs/). 61 623. To make sure you have the right Rust compiler installed, run 63 64 ```sh 65 rustup override set stable 66 rustup update stable 67 ``` 68 69### Dependencies 70 71These are the minimum dependencies required to build Alacritty, please note 72that with some setups additional dependencies might be desired. 73 74If you're running Wayland with an Nvidia GPU, you'll likely want the EGL 75drivers installed too (these are called `libegl1-mesa-dev` on Ubuntu). 76 77#### Debian/Ubuntu 78 79If you'd like to build a local version manually, you need a few extra libraries 80to build Alacritty. Here's an apt command that should install all of them. If 81something is still found to be missing, please open an issue. 82 83```sh 84apt-get install cmake pkg-config libfreetype6-dev libfontconfig1-dev libxcb-xfixes0-dev libxkbcommon-dev python3 85``` 86 87#### Arch Linux 88 89On Arch Linux, you need a few extra libraries to build Alacritty. Here's a 90`pacman` command that should install all of them. If something is still found 91to be missing, please open an issue. 92 93```sh 94pacman -S cmake freetype2 fontconfig pkg-config make libxcb libxkbcommon 95``` 96 97#### Fedora 98 99On Fedora, you need a few extra libraries to build Alacritty. Here's a `dnf` 100command that should install all of them. If something is still found to be 101missing, please open an issue. 102 103```sh 104dnf install cmake freetype-devel fontconfig-devel libxcb-devel libxkbcommon-devel g++ 105``` 106 107#### CentOS/RHEL 7 108 109On CentOS/RHEL 7, you need a few extra libraries to build Alacritty. Here's a `yum` 110command that should install all of them. If something is still found to be 111missing, please open an issue. 112 113```sh 114yum install cmake freetype-devel fontconfig-devel libxcb-devel libxkbcommon-devel xcb-util-devel 115yum group install "Development Tools" 116``` 117 118#### openSUSE 119 120On openSUSE, you need a few extra libraries to build Alacritty. Here's 121a `zypper` command that should install all of them. If something is 122still found to be missing, please open an issue. 123 124```sh 125zypper install cmake freetype-devel fontconfig-devel libxcb-devel 126``` 127 128#### Slackware 129 130Compiles out of the box for 14.2 131 132#### Void Linux 133 134On [Void Linux](https://voidlinux.org), install following packages before 135compiling Alacritty: 136 137```sh 138xbps-install cmake freetype-devel expat-devel fontconfig-devel libxcb-devel pkg-config python3 139``` 140 141#### FreeBSD 142 143On FreeBSD, you need a few extra libraries to build Alacritty. Here's a `pkg` 144command that should install all of them. If something is still found to be 145missing, please open an issue. 146 147```sh 148pkg install cmake freetype2 fontconfig pkgconf 149``` 150 151#### OpenBSD 152 153On OpenBSD 6.5, you need [Xenocara](https://xenocara.org) and Rust to build 154Alacritty, plus Python 3 to build its XCB dependency. If something is still 155found to be missing, please open an issue. 156 157```sh 158pkg_add rust python 159``` 160 161Select the package for Python 3 (e.g. `python-3.6.8p0`) when prompted. 162 163The default user limits in OpenBSD are insufficient to build Alacritty. A 164`datasize-cur` of at least 3GB is recommended (see [login.conf](https://man.openbsd.org/login.conf)). 165 166#### Solus 167 168On [Solus](https://solus-project.com/), you need a few extra libraries to build 169Alacritty. Here's a `eopkg` command that should install all of them. If 170something is still found to be missing, please open an issue. 171 172```sh 173eopkg install fontconfig-devel 174``` 175 176#### NixOS/Nixpkgs 177 178The following command can be used to get a shell with all development 179dependencies on [NixOS](https://nixos.org). 180 181```sh 182nix-shell -A alacritty '<nixpkgs>' 183``` 184 185#### Gentoo 186 187On Gentoo, you need a few extra libraries to build Alacritty. The following 188command should install all of them. If something is still found to be missing, 189please open an issue. 190 191```sh 192emerge --onlydeps x11-terms/alacritty 193``` 194 195#### Clear Linux 196 197On Clear Linux, you need a few extra libraries to build Alacritty. Here's a 198`swupd` command that should install all of them. If something is still found 199to be missing, please open an issue. 200 201```sh 202swupd bundle-add devpkg-expat devpkg-freetype devpkg-libxcb devpkg-fontconfig 203``` 204 205#### GNU Guix 206 207The following command can be used to get a shell with all development 208dependencies on [GNU Guix](https://guix.gnu.org/). 209 210```sh 211guix environment alacritty 212``` 213 214#### Alpine Linux 215 216On Alpine Linux, you need a few extra libraries to build Alacritty. Here's an 217`apk` command that should install all of them. If something is still found to 218be missing, please open an issue. 219 220```sh 221sudo apk add cmake pkgconf freetype-dev fontconfig-dev python3 libxcb-dev 222``` 223 224#### Windows 225 226On windows you will need to have the `{architecture}-pc-windows-msvc` toolchain 227installed as well as [Clang 3.9 or greater](http://releases.llvm.org/download.html). 228 229#### Other 230 231If you build Alacritty on another distribution, we would love some help 232filling in this section of the README. 233 234## Building 235 236### Linux / Windows 237 238```sh 239cargo build --release 240``` 241 242If all goes well, this should place a binary at `target/release/alacritty`. 243 244### macOS 245 246```sh 247make app 248cp -r target/release/osx/Alacritty.app /Applications/ 249``` 250 251## Post Build 252 253There are some extra things you might want to set up after installing Alacritty. 254All the post build instruction assume you're still inside the Alacritty 255repository. 256 257### Terminfo 258 259To make sure Alacritty works correctly, either the `alacritty` or 260`alacritty-direct` terminfo must be used. The `alacritty` terminfo will be 261picked up automatically if it is installed. 262 263If the following command returns without any errors, the `alacritty` terminfo is 264already installed: 265 266```sh 267infocmp alacritty 268``` 269 270If it is not present already, you can install it globally with the following 271command: 272 273``` 274sudo tic -xe alacritty,alacritty-direct extra/alacritty.info 275``` 276 277### Desktop Entry 278 279Many Linux and BSD distributions support desktop entries for adding applications 280to system menus. This will install the desktop entry for Alacritty: 281 282```sh 283sudo cp target/release/alacritty /usr/local/bin # or anywhere else in $PATH 284sudo cp extra/logo/alacritty-term.svg /usr/share/pixmaps/Alacritty.svg 285sudo desktop-file-install extra/linux/Alacritty.desktop 286sudo update-desktop-database 287``` 288 289If you are having problems with Alacritty's logo, you can replace it with 290prerendered PNGs and simplified SVGs available in the `extra/logo/compat` 291directory. 292 293### Manual Page 294 295Installing the manual page requires the additional dependency `gzip`. 296 297```sh 298sudo mkdir -p /usr/local/share/man/man1 299gzip -c extra/alacritty.man | sudo tee /usr/local/share/man/man1/alacritty.1.gz > /dev/null 300``` 301 302### Shell completions 303 304To get automatic completions for Alacritty's flags and arguments you can install the provided shell completions. 305 306#### Zsh 307 308To install the completions for zsh, you can place the `extra/completions/_alacritty` file in any 309directory referenced by `$fpath`. 310 311If you do not already have such a directory registered through your `~/.zshrc`, you can add one like this: 312 313```sh 314mkdir -p ${ZDOTDIR:-~}/.zsh_functions 315echo 'fpath+=${ZDOTDIR:-~}/.zsh_functions' >> ${ZDOTDIR:-~}/.zshrc 316``` 317 318Then copy the completion file to this directory: 319 320```sh 321cp extra/completions/_alacritty ${ZDOTDIR:-~}/.zsh_functions/_alacritty 322``` 323 324#### Bash 325 326To install the completions for bash, you can `source` the `extra/completions/alacritty.bash` file 327in your `~/.bashrc` file. 328 329If you do not plan to delete the source folder of alacritty, you can run 330 331```sh 332echo "source $(pwd)/extra/completions/alacritty.bash" >> ~/.bashrc 333``` 334 335Otherwise you can copy it to the `~/.bash_completion` folder and source it from there: 336 337```sh 338mkdir -p ~/.bash_completion 339cp extra/completions/alacritty.bash ~/.bash_completion/alacritty 340echo "source ~/.bash_completion/alacritty" >> ~/.bashrc 341``` 342 343#### Fish 344 345To install the completions for fish, run 346 347``` 348mkdir -p $fish_complete_path[1] 349cp extra/completions/alacritty.fish $fish_complete_path[1]/alacritty.fish 350``` 351