git.iko.soy/helix
on bbcdcd0 help sign in
helix/book/src/install.md
250 lines 7.5 kB history raw
1# Installing Helix
3<!--toc:start-->
4- [Pre-built binaries](#pre-built-binaries)
5- [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status)
6- [Linux](#linux)
7 - [Ubuntu](#ubuntu)
8 - [Fedora/RHEL](#fedorarhel)
9 - [Arch Linux community](#arch-linux-community)
10 - [NixOS](#nixos)
11 - [AppImage](#appimage)
12- [macOS](#macos)
13 - [Homebrew Core](#homebrew-core)
14- [Windows](#windows)
15 - [Scoop](#scoop)
16 - [Chocolatey](#chocolatey)
17 - [MSYS2](#msys2)
18- [Building from source](#building-from-source)
19 - [Configuring Helix's runtime files](#configuring-helixs-runtime-files)
20 - [Validating the installation](#validating-the-installation)
21 - [Configure the desktop shortcut](#configure-the-desktop-shortcut)
22<!--toc:end-->
24To install Helix, follow the instructions specific to your operating system.
25Note that:
27- To get the latest nightly version of Helix, you need to
28 [build from source](#building-from-source).
30- To take full advantage of Helix, install the language servers for your
31 preferred programming languages. See the
32 [wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
33 for instructions.
35## Pre-built binaries
37Download pre-built binaries from the
38[GitHub Releases page](https://github.com/helix-editor/helix/releases). Add the binary to your system's `$PATH` to use it from the command
39line.
41## Linux, macOS, Windows and OpenBSD packaging status
43Helix is available for Linux, macOS and Windows via the official repositories listed below.
45[![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)
47## Linux
49The following third party repositories are available:
51### Ubuntu
53Helix is available via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor):
55```sh
56sudo add-apt-repository ppa:maveonair/helix-editor
57sudo apt update
58sudo apt install helix
59```
61### Fedora/RHEL
63Helix is available via `copr`:
65```sh
66sudo dnf copr enable varlad/helix
67sudo dnf install helix
68```
70### Arch Linux community
72Releases are available in the `community` repository:
74```sh
75sudo pacman -S helix
76```
77Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available
78in the AUR, which builds the master branch.
80### NixOS
82Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project
83root. Use `nix develop` to spin up a reproducible development shell. Outputs are
84cached for each push to master using [Cachix](https://www.cachix.org/). The
85flake is configured to automatically make use of this cache assuming the user
86accepts the new settings on first use.
88If you are using a version of Nix without flakes enabled,
89[install Cachix CLI](https://docs.cachix.org/installation) and use
90`cachix use helix` to configure Nix to use cached outputs when possible.
92### AppImage
94Install Helix using [AppImage](https://appimage.org/).
95Download Helix AppImage from the [latest releases](https://github.com/helix-editor/helix/releases/latest) page.
97```sh
98chmod +x helix-*.AppImage # change permission for executable mode
99./helix-*.AppImage # run helix
100```
102## macOS
104### Homebrew Core
106```sh
107brew install helix
108```
110## Windows
112Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/)
113or [MSYS2](https://msys2.org/).
115### Scoop
117```sh
118scoop install helix
119```
121### Chocolatey
123```sh
124choco install helix
125```
127### MSYS2
129For 64-bit Windows 8.1 or above:
131```sh
132pacman -S mingw-w64-ucrt-x86_64-helix
133```
135## Building from source
137Clone the repository:
139```sh
140git clone https://github.com/helix-editor/helix
141cd helix
142```
144Compile from source:
146```sh
147cargo install --path helix-term --locked
148```
150This command will create the `hx` executable and construct the tree-sitter
151grammars in the local `runtime` folder. To build the tree-sitter grammars requires
152a c++ compiler to be installed, for example `gcc-c++`.
154> 💡 If you are using the musl-libc instead of glibc the following environment variable must be set during the build
155> to ensure tree-sitter grammars can be loaded correctly:
157> ```sh
158> RUSTFLAGS="-C target-feature=-crt-static"
159> ```
161> 💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch
162> grammars with `hx --grammar fetch` (requires `git`) and compile them with
163> `hx --grammar build` (requires a C++ compiler). This will install them in
164> the `runtime` directory within the user's helix config directory (more
165> [details below](#multiple-runtime-directories)).
167### Configuring Helix's runtime files
169#### Linux and macOS
171Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent:
173```sh
174HELIX_RUNTIME=/home/user-name/src/helix/runtime
175```
177Or, create a symlink in `~/.config/helix` that links to the source code directory:
179```sh
180ln -s $PWD/runtime ~/.config/helix/runtime
181```
183#### Windows
185Either set the `HELIX_RUNTIME` environment variable to point to the runtime files using the Windows setting (search for
186`Edit environment variables for your account`) or use the `setx` command in
187Cmd:
189```sh
190setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
191```
193> 💡 `%userprofile%` resolves to your user directory like
194> `C:\Users\Your-Name\` for example.
196Or, create a symlink in `%appdata%\helix\` that links to the source code directory:
198| Method | Command |
199| ---------- | -------------------------------------------------------------------------------------- |
200| PowerShell | `New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"` |
201| Cmd | `cd %appdata%\helix` <br/> `mklink /D runtime "%userprofile%\src\helix\runtime"` |
203> 💡 On Windows, creating a symbolic link may require running PowerShell or
204> Cmd as an administrator.
206#### Multiple runtime directories
208When Helix finds multiple runtime directories it will search through them for files in the
209following order:
2111. `runtime/` sibling directory to `$CARGO_MANIFEST_DIR` directory (this is intended for
212 developing and testing helix only).
2132. `runtime/` subdirectory of OS-dependent helix user config directory.
2143. `$HELIX_RUNTIME`.
2154. `runtime/` subdirectory of path to Helix executable.
217This order also sets the priority for selecting which file will be used if multiple runtime
218directories have files with the same name.
220### Validating the installation
222To make sure everything is set up as expected you should run the Helix health
223check:
225```sh
226hx --health
227```
229For more information on the health check results refer to
230[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck).
232### Configure the desktop shortcut
234If your desktop environment supports the
235[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html)
236you can configure Helix to show up in the application menu by copying the
237provided `.desktop` and icon files to their correct folders:
239```sh
240cp contrib/Helix.desktop ~/.local/share/applications
241cp contrib/helix.png ~/.icons # or ~/.local/share/icons
242```
244To use another terminal than the system default, you can modify the `.desktop`
245file. For example, to use `kitty`:
247```sh
248sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
249sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
250```