How to install the MoonBit toolchain

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# How to install the MoonBit toolchain

This guide shows how to get `moon`, `moonc` and `moon-lsp` onto a machine, and how to check that Turbo MoonBit can find them. It assumes you already have Turbo MoonBit, or are about to — see [how to install the editor](install.md) for that.

**The editor works without any of this.** Editing, colouring, themes, snippets and terminal windows all run with no toolchain at all. What needs it is completion, the error marks in the gutter, and every command in the MoonBit menu.

## Install it

One command installs the whole toolchain — the compiler, the build system and the language server together:

```bash
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
```

It downloads into `~/.moon`, takes a few hundred megabytes with the standard library bundled, and finishes with:

```
moonbit was installed successfully to ~/.moon
Added "~/.moon/bin" to $PATH in "~/.bashrc"
```

That last line is the one to read twice. The installer edits **one** shell profile; a shell that was already open, and any program started from a desktop launcher, has not read it.

```bash
source ~/.bashrc
```

On Windows, run the PowerShell installer from https://www.moonbitlang.com/download instead. Everything below applies unchanged once it has finished.

## Check it

```bash
moon version --all
```

You should see three lines and a path for each:

```
moon 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moon
moonc v0.10.12+1634b282e (2026-09-07) ~/.moon/bin/moonc
moonrun 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moonrun
```

The language server is a fourth binary in the same directory, and it is worth asking separately, because it is the one the editor needs:

```bash
moon-lsp --version
```

```
v0.10.12+1634b282e (2026-09-07)
```

## Check that the editor finds it

Open any file in a MoonBit project and read the right-hand end of the status bar:

```
 F1 Describe  F2 Save  F3 Open  F6 Window  F10 Menu       1:1  LSP: ready
```

`LSP: ready` means the server started. `LSP: no moon-lsp — curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash` means it was not found, and the message is the command to run.

**Turbo MoonBit looks in three places, in order**: your `PATH`, then `$MOON_HOME/bin` if `MOON_HOME` is set, then `~/.moon/bin`. So the editor finds a toolchain installed the usual way even from a shell that never read the profile the installer edited — which is the case that otherwise looks like the server being broken.

## Variants

- **You install toolchains somewhere else.** Set `MOON_HOME` before running the installer; it honours it, and so does the editor.
- **You already have `moon` but no completion.** Check `moon-lsp --version` specifically. A toolchain unpacked by hand, or a partial upgrade, can leave `moon` working and `moon-lsp` missing.
- **You want to upgrade.** `moon upgrade` replaces the toolchain in place; `moon upgrade --dev` takes the development build. Both leave `MOON_HOME` and your `PATH` alone.
- **You are installing for CI, or into an image.** The installer is an ordinary shell script and takes no flags worth setting; pinning a version means fetching a release from https://www.moonbitlang.com/download rather than using it.
- **You want to be sure the editor is not simply finding it on `PATH`.** Start it with a stripped environment — `env PATH=/usr/bin:/bin turbo-moonbit main.mbt` — and the status bar should still say `LSP: ready`, from `~/.moon/bin`.

## What each binary is for

| Binary | What the editor uses it for |
| --- | --- |
| `moon-lsp` | Completion, hover, definitions, references, symbols and the error marks in the gutter |
| `moon` | Every command in the MoonBit menu — and `moon-lsp` runs it too, to work out what a project holds |
| `moonc` | The compiler, invoked by `moon` |
| `moonrun` | Runs the WebAssembly output, invoked by `moon run` |

`moon-lsp` on its own is not enough: it works a project out by running `moon`, so a machine with the server but not the build system gets a server that starts, is found, and then knows nothing about any file. `scripts/install.sh` checks for exactly that and says so.

## See also

- [How to enable completion](enable-completion.md) — what to do when the server is installed and still says nothing
- [How to run moon commands from the editor](run-moon-commands.md) — the MoonBit menu
- [Colouring and completion](../explanation/colouring-and-completion.md) — why the editor needs a server at all