Getting started

This page covers what you need to build, run, and develop on Helix from a checkout of the repository.

Prerequisites

• A Rust toolchain — Helix's MSRV is 1.90 (set in rust-toolchain.toml and workspace.package.rust-version in Cargo.toml).
• Git.
• A C++14 compatible compiler (GCC or Clang) for tree-sitter grammars.
• On musl-libc: RUSTFLAGS="-C target-feature=-crt-static" to load grammars dynamically.

If you use Nix, the repo includes flake.nix, shell.nix, and default.nix. Run nix develop for a dev shell.

Cloning and building

git clone https://github.com/helix-editor/helix
cd helix
cargo install --path helix-term --locked

For a faster local iteration build:

cargo run -- README.md

For an optimized release build:

cargo install --profile opt \
  --config 'build.rustflags=["-C","target-cpu=native"]' \
  --path helix-term --locked

The four release profiles are defined in Cargo.toml:

Profile	Inherits	Notes
release	—	thin LTO
opt	release	fat LTO, codegen-units = 1, stripped, opt-level = 3
integration	test	turns on opt for helix-core, -tui, -term so integration tests run quickly
dev	(cargo default)	unoptimized, fast compile

Runtime files

The hx binary needs runtime assets from runtime/: tree-sitter grammars, query files, themes, and the tutor. Helix searches for runtime/ in this priority order (see helix-loader/src/lib.rs::prioritize_runtime_dirs):

1. Sibling directory of CARGO_MANIFEST_DIR (development).
2. runtime/ under the user config directory.
3. $HELIX_RUNTIME.
4. HELIX_DEFAULT_RUNTIME (set at build time, used by packagers).
5. runtime/ next to the executable.

For development, exporting HELIX_RUNTIME=$PWD/runtime from the repo root works.

Tree-sitter grammars

Grammars are listed in languages.toml under [[grammar]]. They are fetched and compiled by:

hx --grammar fetch
hx --grammar build

These call into helix-loader/src/grammar.rs. To skip auto-fetching during build, set HELIX_DISABLE_AUTO_GRAMMAR_BUILD.

Running tests

Three test layers are described in docs/CONTRIBUTING.md:

cargo test --workspace                # unit + doc tests
cargo integration-test                # alias for cargo test --features integration --profile integration
cargo doc --no-deps --workspace       # ensure docs build

The cargo integration-test alias is defined in .cargo/config.toml and uses the integration feature gate plus the integration profile (see helix-term/Cargo.toml).

Linting

CI runs these checks (see .github/workflows/build.yml):

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo doc --no-deps --workspace --document-private-items   # RUSTDOCFLAGS=-D warnings

Generated docs

Some pages in book/src/generated/ are produced from code:

cargo xtask docgen

The CI docs job runs this and fails if the result differs from what is committed (see the Check uncommitted documentation changes step in build.yml). Always re-run docgen after touching commands or language definitions.

Two more xtask checks gate releases:

cargo xtask query-check    # validate tree-sitter queries
cargo xtask theme-check    # validate runtime/themes/*.toml

Health check

hx --health runs helix-term::health::print_health which reports clipboard providers, terminal capabilities, and per-language tooling status.

Logs

Pass -v, -vv, or -vvv to enable info, debug, or trace logging. Logs go to the path in helix_loader::log_file() (under the user cache dir by default). Override with --log /tmp/helix.log. From a shell:

cargo run -- -v --log /tmp/helix.log
tail -f /tmp/helix.log

The log macros come from the log crate; output is configured by fern in helix-term/src/main.rs::setup_logging.

Editor

Helix loads its config from helix_loader::config_file() (typically ~/.config/helix/config.toml). Workspace-local config in .helix/config.toml is merged in if the workspace is trusted (see helix-loader/src/workspace_trust.rs).

Run the built-in tutorial:

hx --tutor

Tooling tips from CONTRIBUTING.md

• Use cargo run while developing — the compile delta is much smaller than --release.
• For even faster linking, use mold.
• Print debugging: log::info!("…") and run with cargo run -- -v --log foo.log then tail -f foo.log in another terminal.
• If you don't use the Nix dev shell, you may need rustup component add rust-analyzer because rust-toolchain.toml pins the MSRV but not RA.

See the development workflow page for the rest of the contributor flow.