Configuration

Helix loads configuration from TOML files at startup. This page is a code-tour: it points at the structs that define each section so you can read the source as the source of truth.

File locations

File	Purpose	Resolved by
~/.config/helix/config.toml (XDG path varies)	Global user config	helix_loader::config_file()
<workspace>/.helix/config.toml	Workspace-local config (requires trust)	helix_loader::workspace_config_file()
<workspace>/.helix/languages.toml	Workspace-local language overrides	helix_loader::workspace_lang_config_file()
~/.config/helix/languages.toml	User-level language overrides	helix_loader::lang_config_file()
Repo-bundled languages.toml	Default language definitions	embedded

The XDG path is computed by the etcetera crate (helix-loader/src/lib.rs).

Top-level structure

theme = "dracula"
# or
[theme]
light = "github_light"
dark = "ayu_mirage"
fallback = "ayu_mirage"

[editor]
# many fields, see below

[editor.lsp]
[editor.cursor-shape]
[editor.file-picker]
[editor.statusline]
[editor.indent-guides]
[editor.soft-wrap]
[editor.search]
[editor.whitespace]
[editor.smart-tab]
[editor.gutters]
[editor.bufferline]
[editor.inline-diagnostics]
[editor.auto-pairs]
[editor.auto-save]

[keys.normal]
[keys.insert]
[keys.select]

Core types

Section	Struct	File
Top-level Config	helix_term::config::Config	helix-term/src/config.rs
[theme]	helix_view::theme::Config	helix-view/src/theme.rs
[editor]	helix_view::editor::Config	helix-view/src/editor.rs
[editor.lsp]	helix_view::editor::LspConfig	helix-view/src/editor.rs
[editor.file-picker]	helix_view::editor::FilePickerConfig	helix-view/src/editor.rs
[editor.statusline]	helix_view::editor::StatusLineConfig	helix-view/src/editor.rs
[editor.cursor-shape]	helix_view::editor::CursorShapeConfig	helix-view/src/editor.rs
[editor.soft-wrap]	helix_core::syntax::config::SoftWrap	helix-core/src/syntax/config.rs
[editor.smart-tab]	helix_view::editor::SmartTabConfig	helix-view/src/editor.rs
[editor.indent-guides]	helix_view::editor::IndentGuidesConfig	helix-view/src/editor.rs
[editor.gutters]	helix_view::editor::GutterConfig	helix-view/src/editor.rs
[editor.search]	helix_view::editor::SearchConfig	helix-view/src/editor.rs
[editor.whitespace]	helix_view::editor::WhitespaceConfig	helix-view/src/editor.rs
[editor.auto-pairs]	helix_core::syntax::config::AutoPairConfig	helix-core/src/syntax/config.rs
[editor.auto-save]	helix_view::editor::AutoSave	helix-view/src/editor.rs
[editor.inline-diagnostics]	helix_view::annotations::diagnostics::InlineDiagnosticsConfig	helix-view/src/annotations/diagnostics.rs
[keys.<mode>]	KeyTrie	helix-term/src/keymap.rs

Every struct is documented inline. The TOML field names are the kebab-case version of the Rust field name (via #[serde(rename_all = "kebab-case")]).

Selected [editor] fields

These are the fields most users tweak. The exhaustive list lives in Config::default in helix-view/src/editor.rs.

Field	Default	Notes
mouse	true	Enable mouse support.
scrolloff	5	Lines kept above/below the cursor.
scroll-lines	3	Lines per Ctrl-d/Ctrl-u.
line-number	"absolute"	Or "relative".
cursorline	false	Highlight current line.
cursorcolumn	false	Highlight current column.
auto-completion	true	LSP completion popup.
auto-format	true	Format on save.
auto-save	false (struct with focus-lost and after-delay)	Save on idle.
idle-timeout	250ms	Used by completion + handlers.
completion-timeout	250ms	Debounce for completion requests.
preview-completion-insert	true	Optimistic completion preview.
completion-trigger-len	2	Min chars to trigger completion.
completion-replace	false	Replace word vs insert at cursor.
auto-info	true	Show keymap info popup.
true-color	auto-detected	Force true color.
undercurl	false	Curly underline support.
default-yank-register	"	Default register for y/p.
popup-border	"none"	Or "all", "popup", "menu".
text-width	80	Used by :reflow and rulers.
editor-config	true	Honor .editorconfig.
default-line-ending	"native"	LF/CRLF/native/auto.
insert-final-newline	true	Add trailing newline on save.
atomic-save	true	Write-temp-and-rename save.
trim-trailing-whitespace	false	Strip on save.
trim-final-newlines	false	Strip on save.
clipboard-provider	platform-default	osc52, wayland, x11, win, mac, none.
kitty-keyboard-protocol	platform-default	Use the kitty keyboard protocol where available.

Keymap config

User keymap deserializes into HashMap<Mode, KeyTrie>:

[keys.normal]
C-s = ":write"
"," = "remove_selections"

[keys.normal.space]
f = "file_picker"
F = "file_picker_in_current_buffer_directory"

[keys.insert]
C-space = "completion"

Multi-key sequences nest via subtables. Lists of commands are also valid:

[keys.normal]
"C-d" = ["select_mode", "page_cursor_half_down"]

The merge happens in Config::load (helix-term/src/config.rs) via keymap::merge_keys.

Workspace trust

Workspace-local config (<repo>/.helix/config.toml) is only loaded if the workspace is trusted. The trust list is ~/.local/share/helix/trusted_workspaces (or the platform equivalent). On first encounter, helix-term/src/handlers/workspace_trust.rs prompts the user.

To bypass the trust check, set editor.insecure = true in the global config — but read helix-loader/src/workspace_trust.rs before doing so.

Reload at runtime

:config-reload re-runs the loader and applies the result. Most fields take effect immediately; some (active LSP servers, key bindings) are picked up the next time they are consulted.

See also

• book/src/configuration.md — user-facing documentation with prose.
• book/src/editor.md — exhaustive [editor] reference.
• book/src/themes.md — theme key reference.