# How to install and build Turbo Python

This guide shows how to get a working `turbo-python` binary. It assumes you have Go 1.26 or later and can use a terminal.

## The short way, from a checkout

```bash
git clone ssh://git@rickub.com/turbo-editors/turbo-python.git
cd turbo-python
make install
```

That builds the editor, puts it where your shell looks for commands, and tells you what it found: the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `pylsp` is installed. The build goes to a temporary file first, so a failed build never replaces a working installation.

Then, from any Python project:

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

### Options

```bash
scripts/install.sh --prefix ~/bin     # install somewhere of your choosing
scripts/install.sh --with-pylsp       # install the language server too
scripts/install.sh --uninstall        # remove it again  (make uninstall)
scripts/install.sh --help
```

Without `--prefix`, the editor goes where `go install` would put it: `$GOBIN`, or `$GOPATH/bin` when `GOBIN` is unset — usually `~/go/bin`.

## Just build it, without installing

```bash
make build
./bin/turbo-python main.py
```

## From the module proxy, without a checkout

```bash
go install rickub.com/turbo-editors/turbo-python@latest
```

If the command is then "not found", the install directory is not on your `PATH`:

```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```

## Check it works

```bash
turbo-python -version
turbo-python -list-themes
```

The first names the commit the binary was built from, which is what to quote in a bug report; [the version number](../reference/versioning.md) explains what each form means. The second prints the themes compiled into the binary and tells you where your own would go.

## Variants

- **You only want to run it once**: `go run rickub.com/turbo-editors/turbo-python@latest src/main.py`
- **You want the binary somewhere specific**: `go build -o /usr/local/bin/turbo-python .`
- **Your terminal has no true colour**: use `turbo-python -theme turbo-classic`, which is built from the sixteen ANSI colours only. `turbo-dark` and `borland-light` use 24-bit colours.

## When something goes wrong

**`the installed binary does not run`.** The installer prints whatever the system said just above that line — read it first, because it names the actual problem.

The installer replaces the binary rather than writing over the one that is there, so a reinstall gives the file a fresh identity. That matters on macOS, which caches a binary's code signature against its inode: writing new bytes into the old inode leaves the cached signature describing something else, and the kernel then refuses to run a binary that built and installed perfectly. If you have an older copy installed by something that used `cp`, removing it first clears any such state:

```bash
scripts/install.sh --uninstall
scripts/install.sh
```

**`Go x.y or later is needed`.** The editor is written in Go, so building it needs a Go toolchain even though it is an editor for Python. The version comes from `go.mod`, so it cannot drift from what the code actually needs.

**`build failed; nothing was installed`.** Your existing installation is untouched — the build goes to a temporary file first. The compiler's own output is printed above the message.

## Terminal requirements

Turbo Python needs a terminal that reports its size and supports mouse reporting — every mainstream one does. It reads `TERM` through tcell; if the display is wrong, check that `TERM` matches your terminal (`xterm-256color` is a safe default).

## See also

- Every flag: [command line reference](../reference/cli.md)
- Getting completion working: [How to enable Python completion](enable-completion.md)
- A guided first session: [Your first file in Turbo Python](../tutorials/getting-started.md)