Frequently Asked Questions

How to Run Helix

In the terminal:

hx

Save file without formatting

If you have auto-format turned on, but you want to save a file without formatting, then do the following:

:set-language text
Write the file
Optionally, change it back with :set-language

How to Learn Helix

Check out The Basics section of the editor.

Start Helix tutorial:

hx --tutor

Collapse to single cursor after using multiple cursors / Keep only primary cursor

Use the default keybind , bound to the keep_primary_selection command.

Change cursor shape on mode change (bar cursor on insert mode, block on normal mode, etc)

Add this to your config:

[editor.cursor-shape]
insert = "bar"
normal = "block"
select = "underline"

Map `jk` or `jj` to exit insert mode

Add this to your config:

[keys.insert]
j = { k = "normal_mode" }

Map unicode characters like `ö` to keybinding

The TOML standard requires that these characters are quoted:

[keys.normal]
ö = "extend_line_up" # This line is invalid TOML
"ö" = "extend_line_up" # This line is valid TOML

Use my terminal’s 16 color palette as a theme

Add this to your config:

# to see more "adaptive" themes,
# type `:theme base16_` in Normal mode.
theme = "base16_default"

Refer to the list of themes.

Type % to select the entire file, then s to bring up a select: prompt. Enter your search, and press enter. All matches in the file will be selected; you can now use c to change them all simultaneously.

To make search fully case sensitive add the following to your config:

[editor.search]
smart-case = false

Strip whitespace or format the buffer

If the LSP for the language is active and supports autoformat, and the auto-format option is on (check your and the repo’s languages.toml), then this will happen on save.

If there is an alternative command you can run in the terminal to format, you can pipe the whole buffer to it manually with %|<formatter><enter>.

Access the Helix config directory

You can use :config-open to open the config in Helix.

Platform	Location
MacOS / Linux	`~/.config/helix`
Windows	`%appdata%\Roaming\helix`

Access the log file

Enable logging via the -v flag, with each use (up to -vvv) increasing the verbosity. However, -vv and -vvv are only useful for developing Helix. hx -v is sufficient for diagnosing issues with language servers.

You can use :log-open to open the log in Helix.

Platform	Location
MacOS / Linux	`~/.cache/helix/helix.log`
Windows	`%appdata%\Local\helix\helix.log`

Add a language

Check out the [contributing guide on adding a language].

Change grammars at project level

You can specify custom grammars per-project/per-directory by placing the languages.toml in .helix/languages.toml at the root of your project.

See https://docs.helix-editor.com/languages.html ↗

Ctrl-c closes popups like LSP signature-help, hover, and auto-completion.

General Questions

How to write plugins / Is there a plugin system in place yet?

Current status as of December 2022:

There’s two prototypes we’re exploring that could potentially exist side by side: a typed list/ML-like implementation for scripting and a Rust based interface for things that require performance. Could potentially run both in wasm but I’m personally a bit unhappy with how big wasm implementations are, easily several orders of magnitude compared to the editor

Originally posted in https://github.com/helix-editor/helix/discussions/3806#discussioncomment-4438007 ↗

As of February 2024, this is being worked on in #8675 ↗

Past discussions:

When will the next release be?

Releases don’t have exact timelines. The maintainers aim for a few releases per year and cut a release when they feel that enough changes have collected in master and the branch has stabilized.

Is a Vi/Vim keymap planned?

We are not interested in supporting alternative paradigms.

The core of Helix’s editing is based on Selection -> Action, and it would require extensive changes to create a true Vi/Vim keymap. However, there are 3rd party solutions:

A keymap: helix-vim ↗
A fork: evil-helix ↗

Can the `j`/`k` bindings be changed to ignore soft wrapping when using a count like `3j`

j and k are intentionally mapped to visual vertical movement. This is a more intuitive default that makes working with heavily soft-wrapped text (like this Markdown document) much easier. Textual vertical movement is bound to gk and gj. So you can use 3gj and 3gk instead of 3j and 3k to jump to a relative line number.

These commands are intentionally separate (with no special casing for count != 0) as they represent the fundamental vertical movement primitives. All other vertical movement behavior can be created by combining these commands using conditions. For example:

(if (!= count 0) (move_line_up count) (move_vertical_line_up 0))

If these fundamental primitives had such special handling built in, that would limit what could be implemented. Furthermore, helix is slightly opinionated towards unsurprising and consistent behavior.

Pressing `x` when on an empty line selects the next line, is that a bug/how do I change that?

This behavior is by design. Pressing x will extend the selection to the current line unless the current line is already selected. If the line is already selected it will extend the selection to the next line. This allows repeatedly pressing x to quickly select a few lines.

In the case of an empty line, the entire line is already selected (since there is only a newline character on the line). The intention is to use selections interactively so you would not press x in this case because the line is already selected. For example, if you wanted to delete an empty line you would just press d.

In cases where you always want to extend the selection to the line bounds and never want to extend to the next line you can use X. For example, if you want a key combination to blindly mash to delete a line that would be Xd.

How do I build or run code from within Helix?

This is not currently supported. You should build and run code in a separate terminal pane or split.

Are LSP extensions supported?

Helix aims to support only the official parts of the LSP specification in its codebase.

Some language servers extend the LSP specification to add custom methods and notifications. For example rust-analyzer adds a custom rust-analyzer/expandMacro request to provide its macro expansion feature: https://rust-analyzer.github.io/manual.html#expand-macro-recursively ↗.

Extensions to the LSP spec should be implemented in language-specific plugins once the plugin system is available.

Installation

Error when building tree-sitter language grammars in Fedora

Ensure that you have a C compiler installed:

sudo dnf group install "C Development Tools and Libraries"

Common Issues

`Alt-*` key combinations do not work on MacOS iTerm2

Ensure that you have mapped the Option key to ESC+ in the iTerm2 preferences via Preferences > Profiles > Keys

Previous issues: