# How to enable Python completion

This guide shows how to get completion, hovers and go-to-definition working. It assumes Turbo Python is already installed and that you know what a Python project is.

Completion comes from **pylsp**, the official Python language server. Turbo Python does not bundle it: editing and colouring work without it, and only completion is lost.

## 1. Install pylsp

```bash
pipx component add pylsp
```

## 2. Make sure Turbo Python can find it

Turbo Python looks on `PATH` first, then in `$GOBIN`, then in `$GOPATH/bin`. `go install` writes to the last of those, which is very often not on `PATH` — so this usually works without any further step. Check:

```bash
pylsp version
```

If that says "command not found" but Turbo Python still finds it, that is expected and fine.

## 3. Open a file inside a module

```bash
cd /path/to/your/module   # the directory holding pyproject.toml
turbo-python main.py
```

Turbo Python walks up from the file looking for `pyproject.toml` and starts pylsp in the directory it finds. **Outside a module, pylsp has very little to say** — this is the most common reason completion appears not to work.

## 4. Ask for a completion

Put the cursor after a dot and press **Ctrl-Space**:

```go
fmt.
```

A list drops down under the cursor. Keep typing to narrow it, **↑ ↓** to walk it, **Enter** or **Tab** to accept, **Escape** to dismiss.

Typing a `.` asks for a completion by itself, so most of the time you do not press anything.

## Checking what the server is doing

The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none. `Run ▸ Language server status` shows the same thing in a box.

## Variants

**You do not want a language server at all:**

```bash
turbo-python -no-lsp main.py
```

**Completion is dead in a window that started without a name.** An Untitled window has no file to announce to pylsp until it is saved — press **F2** and give it a name ending in `.py`, somewhere under the project. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.

**Completion is empty in a file that does compile.** pylsp needs the file's package to build. Check `uv sync` first — a package that does not compile often yields nothing useful.

**The first completion after opening a large module is slow.** pylsp is loading the module graph. The status bar says `LSP: starting…` until it is ready; requests made before then are refused rather than queued.

**A request takes too long.** Every request gives up after three seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.

**The list is empty in a file that does not compile.** pylsp answers *nothing at all* — no error, an empty list — for a package it cannot load. A duplicate declaration or an unresolved import is enough. The editor now says which problem is in the way:

```
No completions — this file does not compile: main redeclared in this block
```

`Run ▸ Language server status` shows the same thing with the server's path, the workspace root, and whether it has been told about this file. Fix the package first — `uv sync` is the quickest check.

**Ctrl-Space does nothing.** tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Type a `.` instead, which asks for a completion by itself, or use `Run ▸ Completion`.

## What else the server gives you

Completion is the loudest thing it does and the least of what it knows. The same connection answers eight more questions, all of them in the **Code** menu and all of them about the symbol under the cursor — no selection needed.

| Key | What it does |
| --- | --- |
| **Ctrl-Space** | Completion list |
| **F1** | Describe the symbol under the cursor |
| **F12** | Jump to where it is declared |
| **Shift-F12** | List everywhere it is used |
| **Ctrl-T** | Find a symbol by name anywhere in the project |

And, without a key: *Go to type definition*, *Find implementations…*, *Symbol in file…* and *Problems…*.

Problems it finds arrive unasked. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a mark in the gutter (`×` for an error, `!` for a warning); and **Code ▸ Problems…** lists all of them, for every file the server has loaded.

[How to ask what the code means](ask-about-code.md) walks through all of it.

## See also

- Why the server is optional: [Colouring and completion](../explanation/colouring-and-completion.md)
- Every key: [keyboard reference](../reference/keyboard.md)