Skip to content

How to Configure Helix for a uv Project

by Tim Hopper · Markdown
uv
This guide assumes a Python project managed with uv. If you haven’t created a project yet, see the project creation tutorial.

Helix uses language servers for Python support and reads its configuration from ~/.config/helix/languages.toml. This guide sets up Ruff for formatting and linting, and ty for type checking, both installed with uv.

Install language servers

Install Ruff and ty as standalone tools:

uv tool install ruff
uv tool install ty

Verify both are on your PATH:

ruff --version
ty --version

If these commands fail, ensure ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows) is in your PATH. See How to install uv for platform-specific PATH setup.

Configure language servers

Add the following to ~/.config/helix/languages.toml:

[language-server.ruff]
command = "ruff"
args = ["server"]

[language-server.ty]
command = "ty"
args = ["server"]

[[language]]
name = "python"
language-servers = ["ruff", "ty"]
auto-format = true
formatter = { command = "ruff", args = ["format", "-"] }

Ruff serves as both the linter and the formatter, handling lint diagnostics, import organization, and code formatting. ty provides type-error diagnostics, completions, and go-to-definition.

Tip

Run hx --health python to verify that Helix detects both language servers. The output lists each configured server and its status.

Verify virtual environment detection

Ruff and ty both auto-detect .venv directories at the project root. Run uv sync to create the virtual environment, then launch Helix from the project directory:

cd my-project
hx src/main.py

Open a Python file that imports a project dependency. If the import shows no error diagnostic, the language server found the virtual environment.

Note

Helix must be launched from the directory containing .venv (or a parent of it). If you open Helix from a different directory, the language servers won’t find the virtual environment and imports will show false errors.

Customize Ruff settings

Ruff reads your project’s pyproject.toml or ruff.toml for lint and format rules. To override settings at the editor level, add them to languages.toml:

[language-server.ruff.config.settings]
lineLength = 88

[language-server.ruff.config.settings.lint]
select = ["E", "F", "I"]

Editor-level overrides apply to all projects. Project-level configuration in pyproject.toml is usually the better choice so that rules stay consistent across editors and CI.

Use basedpyright instead of ty (optional)

Basedpyright is a more mature type checker with broader rule coverage. To use it instead of ty:

uv tool install basedpyright

Then update languages.toml:

[language-server.basedpyright]
command = "basedpyright-langserver"
args = ["--stdio"]

[[language]]
name = "python"
language-servers = ["ruff", "basedpyright"]
auto-format = true
formatter = { command = "ruff", args = ["format", "-"] }

Combine the full configuration

Here is a full ~/.config/helix/languages.toml for a uv project using Ruff and ty:

[language-server.ruff]
command = "ruff"
args = ["server"]

[language-server.ty]
command = "ty"
args = ["server"]

[[language]]
name = "python"
language-servers = ["ruff", "ty"]
auto-format = true
formatter = { command = "ruff", args = ["format", "-"] }

Per-project overrides go in .helix/languages.toml at the project root. Helix merges project-level configuration on top of the global file.

Learn More

Last updated on
How to configure Cursor rules to use uvHow to configure mypy and django-stubs in a uv project