| 📦 Turbo MoonBit cc1f595 k33g 13h ago | 1 | # How to install the MoonBit toolchain |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | **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. |
| 6 | |
| 7 | ## Install it |
| 8 | |
| 9 | One command installs the whole toolchain — the compiler, the build system and the language server together: |
| 10 | |
| 11 | ```bash |
| 12 | curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash |
| 13 | ``` |
| 14 | |
| 15 | It downloads into `~/.moon`, takes a few hundred megabytes with the standard library bundled, and finishes with: |
| 16 | |
| 17 | ``` |
| 18 | moonbit was installed successfully to ~/.moon |
| 19 | Added "~/.moon/bin" to $PATH in "~/.bashrc" |
| 20 | ``` |
| 21 | |
| 22 | 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. |
| 23 | |
| 24 | ```bash |
| 25 | source ~/.bashrc |
| 26 | ``` |
| 27 | |
| 28 | On Windows, run the PowerShell installer from https://www.moonbitlang.com/download instead. Everything below applies unchanged once it has finished. |
| 29 | |
| 30 | ## Check it |
| 31 | |
| 32 | ```bash |
| 33 | moon version --all |
| 34 | ``` |
| 35 | |
| 36 | You should see three lines and a path for each: |
| 37 | |
| 38 | ``` |
| 39 | moon 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moon |
| 40 | moonc v0.10.12+1634b282e (2026-09-07) ~/.moon/bin/moonc |
| 41 | moonrun 0.1.20260904 (94521db 2026-09-04) ~/.moon/bin/moonrun |
| 42 | ``` |
| 43 | |
| 44 | 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: |
| 45 | |
| 46 | ```bash |
| 47 | moon-lsp --version |
| 48 | ``` |
| 49 | |
| 50 | ``` |
| 51 | v0.10.12+1634b282e (2026-09-07) |
| 52 | ``` |
| 53 | |
| 54 | ## Check that the editor finds it |
| 55 | |
| 56 | Open any file in a MoonBit project and read the right-hand end of the status bar: |
| 57 | |
| 58 | ``` |
| 59 | F1 Describe F2 Save F3 Open F6 Window F10 Menu 1:1 LSP: ready |
| 60 | ``` |
| 61 | |
| 62 | `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. |
| 63 | |
| 64 | **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. |
| 65 | |
| 66 | ## Variants |
| 67 | |
| 68 | - **You install toolchains somewhere else.** Set `MOON_HOME` before running the installer; it honours it, and so does the editor. |
| 69 | - **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. |
| 70 | - **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. |
| 71 | - **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. |
| 72 | - **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`. |
| 73 | |
| 74 | ## What each binary is for |
| 75 | |
| 76 | | Binary | What the editor uses it for | |
| 77 | | --- | --- | |
| 78 | | `moon-lsp` | Completion, hover, definitions, references, symbols and the error marks in the gutter | |
| 79 | | `moon` | Every command in the MoonBit menu — and `moon-lsp` runs it too, to work out what a project holds | |
| 80 | | `moonc` | The compiler, invoked by `moon` | |
| 81 | | `moonrun` | Runs the WebAssembly output, invoked by `moon run` | |
| 82 | |
| 83 | `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. |
| 84 | |
| 85 | ## See also |
| 86 | |
| 87 | - [How to enable completion](enable-completion.md) — what to do when the server is installed and still says nothing |
| 88 | - [How to run moon commands from the editor](run-moon-commands.md) — the MoonBit menu |
| 89 | - [Colouring and completion](../explanation/colouring-and-completion.md) — why the editor needs a server at all |