# How to Configure Helix for a uv Project

{{< callout type="warning" >}}
This guide assumes a Python project managed with [uv](https://pydevtools.com/handbook/reference/uv.md). If you haven't created a project yet, see the [project creation tutorial](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md).
{{< /callout >}}

Helix uses language servers for Python support and reads its configuration from `~/.config/helix/languages.toml`. This guide sets up [Ruff](https://pydevtools.com/handbook/reference/ruff.md) for formatting and linting, and [ty](https://pydevtools.com/handbook/reference/ty.md) for type checking, both installed with uv.

## Install language servers

Install Ruff and ty as standalone tools:

```bash
uv tool install ruff
uv tool install ty
```

Verify both are on your `PATH`:

```bash
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](https://pydevtools.com/handbook/how-to/how-to-install-uv.md) for platform-specific PATH setup.

## Configure language servers

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

```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:

```bash
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`:

```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](https://pydevtools.com/handbook/reference/basedpyright.md) is a more mature type checker with broader rule coverage. To use it instead of ty:

```bash
uv tool install basedpyright
```

Then update `languages.toml`:

```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:

```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", "-"] }
```

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

- [Helix language support](https://docs.helix-editor.com/lang-support.html) lists all supported languages and their default language servers
- [Ruff editor setup](https://docs.astral.sh/ruff/editors/setup/) describes Helix-specific Ruff configuration
- [Helix, language servers, and Python virtual environments](https://www.seanh.cc/2025/10/13/helix-lsp-virtualenv/) is a detailed walkthrough of virtual environment detection behavior
- [How to configure VS Code for a uv project](https://pydevtools.com/handbook/how-to/how-to-configure-vs-code-for-a-uv-project.md) is the equivalent guide for VS Code