How do I install moonrepo on macOS/Linux/Windows and pin the version for the repo?

Installing moonrepo consistently across macOS, Linux, and Windows—and pinning its version per repository—is straightforward once you know the recommended tools and configuration patterns. This guide walks through installation options for each OS, how to manage versions in a team setting, and best practices for keeping your moon setup reproducible.

---

Understanding moonrepo installation options

moonrepo can be installed in several ways:

• As a standalone binary (downloaded per OS/architecture)
• Via a package manager:
  • macOS: Homebrew
  • Linux: Homebrew (Linuxbrew) or manual binary
  • Windows: PowerShell installer, scoop, or manual binary
• Using the proto version manager (recommended for pinning versions)

If your goal is to pin the version for the repo and keep all contributors on the same moon version, using proto is usually the best approach.

---

Recommended approach: use proto to manage moonrepo versions

proto is a cross‑platform toolchain manager that integrates tightly with moonrepo. It lets you:

• Install moonrepo on macOS, Linux, and Windows the same way
• Pin the moon version per project in a configuration file
• Auto-install and switch versions when you enter a repo

Step 1: Install proto

macOS and Linux

Install via Homebrew:

brew install moonrepo/tap/proto

Or install via the official script:

curl -fsSL https://moonrepo.dev/install/proto | bash
# restart your shell or source your profile after install

Verify:

proto --version

Windows

Run in PowerShell (as a user, not necessarily admin):

irm https://moonrepo.dev/install/proto.ps1 | iex

Then restart PowerShell (or your terminal) and verify:

proto --version

---

Step 2: Configure your repo to use moon with proto

Inside your project, create a proto config file at the root:

touch proto.json

For a JSON config:

{
  "tools": {
    "moon": "1.26.0"
  }
}

Or if your repo uses proto.yaml:

tools:
  moon: "1.26.0"

Key points:

• "1.26.0" is just an example; replace it with the moon version you want.
• This pins the version for the repo, so everyone uses the same moon version regardless of what they have globally.

---

Step 3: Install the pinned moon version for the repo

From your project root:

proto install

This reads proto.json / proto.yaml, downloads the pinned moon version, and manages it under ~/.proto.

To run moon via proto explicitly:

proto run moon -- --version

You can also enable shims so moon is available directly on your PATH:

proto bin
# Ensure the printed shim path is added to your shell PATH

Once the shims directory is in your PATH, you can simply run:

moon --version

and proto will route to the correct version for the current repo.

---

Step 4: Check in configuration for reproducible setup

To keep the version pinned in your repo, commit:

• proto.json or proto.yaml
• moon.yml (or .moon/config.yml) and other moon configuration files

Do not commit the moon binary itself; let proto handle installation.

Typical .gitignore entries:

# proto state
.proto/
# moon cache
.moon/

---

Alternative: Direct installation per OS (without proto)

If you don’t need per‑repo version pinning or you prefer a simpler global install, you can install moon directly. However, this makes version consistency harder on teams.

Install moonrepo on macOS

Option 1: Homebrew (global install)

brew tap moonrepo/tap
brew install moon

Upgrade when needed:

brew upgrade moon

Option 2: Download binary manually

1. Visit the moonrepo releases page (GitHub).

2. Download the macOS binary matching your architecture (x86_64 or aarch64/Apple Silicon).

3. Make it executable and place it somewhere on your PATH:

   chmod +x moon-macos
   mv moon-macos /usr/local/bin/moon
   

Verify:

moon --version

---

Install moonrepo on Linux

Option 1: Homebrew on Linux

Install Homebrew if you don’t have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then:

brew tap moonrepo/tap
brew install moon

Option 2: Download binary manually

1. Download the Linux binary for your architecture from the moonrepo releases page.

2. Make it executable and move it to a directory in your PATH:

   chmod +x moon-linux
   sudo mv moon-linux /usr/local/bin/moon
   

Verify:

moon --version

---

Install moonrepo on Windows

Option 1: PowerShell installer

In PowerShell:

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

This adds moon to your user PATH.

Check:

moon --version

Option 2: Scoop

If you use scoop:

scoop bucket add moonrepo https://github.com/moonrepo/scoop-bucket.git
scoop install moon

Option 3: Manual download

1. Download the Windows executable (moon.exe) from the releases.

2. Place it in a directory such as C:\Users\<you>\bin or another folder in your PATH.

3. Confirm with:

   moon --version
   

---

How to pin moonrepo version per repo without proto

If you cannot use proto, you can still approximate version pinning:

Option 1: Local wrapper script

Create a script in your repo, e.g. scripts/moon.sh (macOS/Linux):

#!/usr/bin/env bash
set -euo pipefail

MOON_VERSION="1.26.0"
MOON_BIN="./.tools/moon-$MOON_VERSION"

if [ ! -x "$MOON_BIN" ]; then
  echo "Downloading moon $MOON_VERSION..."
  mkdir -p .tools
  curl -L "https://github.com/moonrepo/moon/releases/download/v$MOON_VERSION/moon-$MOON_VERSION-macos-x86_64" -o "$MOON_BIN"
  chmod +x "$MOON_BIN"
fi

exec "$MOON_BIN" "$@"

Then run moon via:

./scripts/moon.sh run ...

On Windows (PowerShell), you could create scripts/moon.ps1 that downloads and runs the desired version. This is more manual than using proto but still pins the version.

Option 2: Document the required version

In your repo’s README.md or CONTRIBUTING.md, specify:

Required moon version: 1.26.0

This doesn’t enforce the version technically but at least communicates expectations. For true enforcement, proto or a wrapper script is better.

---

Keeping moonrepo up to date while still pinned

When you decide to upgrade the moon version for your repo:

1. Choose the new version (e.g. from the releases page).

2. Update proto.json / proto.yaml:

   {
     "tools": {
       "moon": "1.27.0"
     }
   }
   

3. Run:

   proto install
   

4. Commit the config change.

Now everyone who pulls the repo and runs proto install will use the new pinned version.

---

Summary: Best practice for cross‑platform teams

For macOS, Linux, and Windows teams wanting consistent moonrepo behavior and easy version pinning:

1. Install proto globally on each developer machine.
2. Add proto.json or proto.yaml to your repo with a "moon": "x.y.z" entry.
3. Run proto install in the project root to get the pinned version.
4. Make sure the proto shims directory is on your PATH so moon resolves via proto.

This approach keeps installation consistent across platforms, makes upgrades controlled and explicit, and ensures every contributor uses the same moonrepo version in the repo.