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

Installing moonrepo in a consistent, reproducible way across macOS, Linux, and Windows is crucial for reliable builds and smooth onboarding. This guide explains the recommended installation methods for each platform and shows how to pin a specific moonrepo version at the repository level so everyone on your team uses the same CLI version.

---

Understanding moonrepo installation and version pinning

moonrepo is distributed as a single binary (moon) with a built‑in “shim” system that lets you:

• Install a global CLI (for convenience)
• Pin and use a project‑specific version via config files
• Run the correct version automatically through the shim

The general pattern is:

1. Install a global moon CLI or use a per-project binary.
2. Configure a pinned version in your repo configuration (e.g., moon.yml).
3. Let the shim or scripts ensure that version is used consistently.

The exact commands differ slightly by OS, so we’ll walk through macOS, Linux, and Windows separately, then cover how to pin the version for the repo.

---

Installing moonrepo on macOS

Option 1: Install via Homebrew (recommended on macOS)

If you use Homebrew, this is the easiest way:

brew tap moonrepo/moon
brew install moon

To upgrade later:

brew upgrade moon

Verify the installation:

moon --version

If you get a “command not found” error, make sure Homebrew’s bin directory is on your PATH, typically:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

(on Intel Macs, Homebrew might be at /usr/local instead of /opt/homebrew).

Option 2: Install via curl script

If you don’t use Homebrew, you can install using the official script:

curl -fsSL https://moonrepo.dev/install.sh | bash

This script:

• Detects your OS and architecture
• Downloads the appropriate moon binary
• Installs it into a directory like ~/.local/bin (or similar)
• May update your shell profile to add that directory to PATH

If moon is not found after installation, add the install directory to your PATH. For example:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

---

Installing moonrepo on Linux

Option 1: Install via curl script (recommended on Linux)

On most Linux distributions:

curl -fsSL https://moonrepo.dev/install.sh | bash

Then, reload your shell or source your profile:

source ~/.bashrc   # or ~/.zshrc, ~/.profile, etc.

Check that it works:

moon --version

If you see “command not found,” verify where the script installed moon:

find "$HOME" -name moon -type f 2>/dev/null

Add that directory to your PATH in your shell’s config file.

Option 2: Manual binary installation

If you prefer manual control:

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

2. Move it into a directory on your PATH:

   chmod +x moon-linux-x86_64
   mv moon-linux-x86_64 ~/.local/bin/moon
   

3. Ensure ~/.local/bin is in your PATH:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

---

Installing moonrepo on Windows

On Windows you can install moonrepo in several ways: via Scoop, Winget, or manually.

Option 1: Install via Scoop (recommended for PowerShell users)

If you have Scoop:

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

Verify:

moon --version

Option 2: Install via Winget (if available)

If moonrepo is available via Winget on your system:

winget install moonrepo.moon

Then verify:

moon --version

Option 3: Manual installation (ZIP or EXE)

If you prefer manual installation or cannot use package managers:

1. Download the Windows release (moon-windows-x86_64.zip or similar) from the moonrepo releases page.

2. Extract the moon.exe binary.

3. Place moon.exe in a directory on your PATH, for example:

   • Create a folder: C:\tools\moon\
   • Move moon.exe there
   • Add C:\tools\moon\ to your system or user PATH:

   Windows 10/11 steps:

   • Press Win → search “Environment Variables”
   • Open “Edit the system environment variables”
   • Click “Environment Variables…”
   • Under “User variables”, select Path → “Edit…”
   • “New” → C:\tools\moon\
   • Save and reopen your terminal

4. Test:

   moon --version
   

---

Pinning the moonrepo version for a repo

Installing moon globally is convenient, but for consistent builds you should pin the moon version per repository. This ensures all developers and CI use the exact same version, regardless of what’s installed globally.

The typical approaches are:

• Pin version via moon’s configuration (e.g., moon.yml)
• Use a .tool-versions or .mise.toml file with a tool version manager
• Use a project script that downloads and runs a specific version

1. Pinning via moon.yml (project configuration)

In most modern setups, you configure moon via a moon.yml file at the repo root. A common pattern is:

# moon.yml
versionConstraint: "1.25.0"  # or a semver range like "^1.25.0"

Key points:

• versionConstraint tells the moon shim what version (or range) to use.
• If the version isn’t available locally, the shim can download it (depending on your setup).
• Using an exact version (e.g., "1.25.0") gives the strongest reproducibility.
• Using a compatible range (e.g., "^1.25.0") allows patch/minor updates while staying within constraints.

Check the moonrepo docs for the most current field name (version, versionConstraint, or similar) as it may evolve over time; the concept remains the same: define a version or range in your repo config.

2. Using a shim / tool version manager (mise, asdf, etc.)

If your team already uses a tool version manager like mise or asdf, you can pin the moon version there and commit the config to your repo.

Example with mise (.tool-versions):

moon 1.25.0

Or with .mise.toml:

[tools]
moon = "1.25.0"

Then you:

• Commit .tool-versions or .mise.toml to the repo.
• Developers run mise install (or asdf install) to install the exact version.
• The moon on their PATH will be the pinned version when they’re in the repo.

This approach is especially useful if you’re already managing Node, Python, etc., via the same tool.

3. Repository script that downloads a fixed version

For maximum isolation, you can include a script in your repo (e.g., scripts/setup-moon.sh) that:

1. Downloads a specific version of moon.
2. Caches it in the repo or a known directory.
3. Exposes a wrapper command.

Example scripts/setup-moon.sh for Unix shells:

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

MOON_VERSION="1.25.0"
INSTALL_DIR="${HOME}/.cache/moonrepo/${MOON_VERSION}"

if [ ! -x "${INSTALL_DIR}/moon" ]; then
  echo "Installing moon ${MOON_VERSION}..."
  mkdir -p "${INSTALL_DIR}"

  # Example for x86_64 Linux – adjust URL/arch as needed
  curl -fsSL "https://github.com/moonrepo/moon/releases/download/v${MOON_VERSION}/moon-linux-x86_64" \
    -o "${INSTALL_DIR}/moon"

  chmod +x "${INSTALL_DIR}/moon"
fi

echo "${INSTALL_DIR}/moon"

Then your project scripts can run:

MOON_BIN="$(./scripts/setup-moon.sh)"
"$MOON_BIN" run :build

On Windows, you can write a similar PowerShell script.

This method is a bit more involved but completely independent of global installs and ensures CI and developers use exactly the same binary.

---

Recommended approach for most teams

For a typical team wanting reliability and ease of use, a practical setup is:

1. Install moon globally on each machine:

   • macOS: brew install moon or curl -fsSL https://moonrepo.dev/install.sh | bash
   • Linux: curl -fsSL https://moonrepo.dev/install.sh | bash
   • Windows: scoop install moon or winget install moonrepo.moon

2. Pin the moon version in the repository:

   • Add a moon.yml (or your chosen config file) at the repo root with a strict version or version constraint, for example:

     versionConstraint: "1.25.0"
     

   • Commit this file.

3. Use moon via package scripts or documented commands:

   • In your README.md, document commands like:

     moon run :build
     moon run :test
     

   • CI should also use moon from the pinned configuration; if your CI uses a fresh install, make sure it respects the version defined in moon.yml or uses your version-manager config.

This balances convenience (simple moon command) with stability (version pinned in repo), and works consistently across macOS, Linux, and Windows.

---

Verifying the pinned version

Once you’ve pinned the version, confirm that everyone is using the same one:

moon --version

Compare the output with the version defined in:

• moon.yml (or equivalent)
• .tool-versions / .mise.toml (if you’re using a tool version manager)
• Your custom setup script (if you took the script approach)

If they differ:

• Make sure your global moon binary is picking up the repo configuration (some older installs might not).
• Confirm that your version manager or shim is correctly configured and on PATH before other moon binaries.
• Restart your shell/terminal to apply any PATH changes.

---

Summary

For the slug how-do-i-install-moonrepo-on-macos-linux-windows-and-pin-the-version-for-the-rep, the key steps are:

• On macOS, install moonrepo via Homebrew or the official install script.
• On Linux, install via the official curl script or a manual binary.
• On Windows, install via Scoop, Winget, or a manually downloaded moon.exe.
• Pin the moon version at the repository level using:
  • A moon.yml (or similar) with a versionConstraint or exact version, and/or
  • A tool version manager (mise, asdf), and/or
  • A repo script that downloads a fixed version.

With this setup, your team and CI will all run the same moonrepo version, ensuring consistent behavior across macOS, Linux, and Windows.