---
title: Install moon
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HeaderLabel from '@site/src/components/Docs/HeaderLabel';
import NextSteps from '@site/src/components/NextSteps';
import AddDepsTabs from '@site/src/components/AddDepsTabs';

<HeaderLabel text="2 min" />

The following guide can be used to install moon and integrate it into an existing repository (with
or without incremental adoption), or to a fresh repository.

## Installing

The entirety of moon is packaged and shipped as a single binary. It works on all major operating
systems, and does not require any external dependencies. For convenience, we provide the following
scripts to download and install moon.

### proto

moon can be installed and managed in [proto's toolchain](/proto). This will install moon to
`~/.proto/tools/moon` and make the binary available at `~/.proto/bin`.

```shell
proto install moon
```

Furthermore, the version of moon can be pinned on a per-project basis using the
[`.prototools` config file](/docs/proto/config).

```toml title=".prototools"
moon = "2.0.0"
```

:::info

We suggest using proto to manage moon (and other tools), as it allows for multiple versions to be
installed and used. The other installation options only allow for a single version (typically the
last installed).

:::

### Linux, macOS, WSL

In a terminal that supports Bash, run:

```shell
bash <(curl -fsSL https://moonrepo.dev/install/moon.sh)
```

This will install moon to `~/.moon/bin`. You'll then need to set `PATH` manually in your shell
profile.

```shell
export PATH="$HOME/.moon/bin:$PATH"
```

### Windows

In Powershell or Windows Terminal, run:

```shell
irm https://moonrepo.dev/install/moon.ps1 | iex
```

This will install moon to `~\.moon\bin` and prepend to the `PATH` environment variable for the
current session. To persist across sessions, update `PATH` manually in your system environment
variables.

:::info

If you are using Git Bash on Windows, you can run the [Unix commands](#linux-macos-wsl) above.

:::

### npm

moon is also packaged and shipped as a single binary through the
[`@moonrepo/cli`](https://www.npmjs.com/package/@moonrepo/cli) npm package. Begin by installing this
package at the root of the repository.

<AddDepsTabs dep="@moonrepo/cli" dev />

If you are installing with Bun, you'll need to add `@moonrepo/cli` as a
[trusted dependency](https://bun.sh/docs/install/lifecycle#trusteddependencies).

:::info

When a global `moon` binary is executed, and the `@moonrepo/cli` binary exists within the
repository, the npm package version will be executed instead. We do this because the npm package
denotes the exact version the repository is pinned it.

:::

### Nix

On Linux, moon can be run directly from the flake in the repository, without installing anything
first.

```shell
nix run github:moonrepo/moon -- --version
```

Append any git ref that contains `flake.nix` to build that revision instead, such as
`github:moonrepo/moon/master`. To keep moon around, install it into your profile.

```shell
nix profile install github:moonrepo/moon
```

For a flake based NixOS or home-manager setup, add moon as an input and take the package from it.

```nix
{
  inputs.moon.url = "github:moonrepo/moon";

  outputs = { nixpkgs, moon, ... }: {
    # Somewhere in your configuration
    environment.systemPackages = [ moon.packages.x86_64-linux.default ];
  };
}
```

moon is also in [nixpkgs](https://search.nixos.org/packages?query=moon), but that package is updated
separately from this repository and may lag behind the latest release.

### Other

moon can also be downloaded and installed manually, by downloading an asset from
[https://github.com/moonrepo/moon/releases](https://github.com/moonrepo/moon/releases). Be sure to
rename the file after downloading, and apply the executable bit (`chmod +x`) on macOS and Linux.

## Upgrading

If using proto, moon can be upgraded using the following command:

```shell
proto install moon --pin
```

Otherwise, moon can be upgraded with the [`moon upgrade`](./commands/upgrade) command. However, this
will only upgrade moon if it was installed in `~/.moon/bin`.

```shell
moon upgrade
```

Otherwise, you can re-run the installers above and it will download, install, and overwrite with the
latest version.

## Next steps

<NextSteps
  links={[{ icon: 'workspace-config', label: 'Setup workspace', url: './setup-workspace' }]}
/>
