title: Installation outline: deep

Installation

Installing Mago is a quick process with several options to suit your environment and preferences.

Shell installer (macOS & Linux)

This is the recommended method for most macOS and Linux users. Our script automatically downloads the correct binary for your system and adds it to your path.

Using curl

curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash

Using wget

wget -qO- https://carthage.software/mago.sh | bash

Installing a specific version

To install a specific version of Mago, use the --version= flag:

curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash -s -- --version=1.19.0

Or with wget:

wget -qO- https://carthage.software/mago.sh | bash -s -- --version=1.19.0

Manual download

You can always download a pre-compiled binary directly from our GitHub Releases page. This is the recommended method for Windows and a reliable fallback for other systems.

1. Navigate to the Mago releases page.
2. Download the appropriate archive for your operating system (e.g., mago-x86_64-pc-windows-msvc.zip for Windows).
3. Unzip the archive.
4. Place the mago.exe (or mago) executable in a directory that is part of your system's PATH environment variable.

Docker

The official container image provides a zero-install way to run Mago in any environment. The image is built from scratch and weighs only ~26 MB.

docker run --rm -v $(pwd):/app -w /app ghcr.io/carthage-software/mago lint

Available tags include latest, exact versions (e.g., 1.19.0), minor versions (1.19), and major versions (1). Both linux/amd64 and linux/arm64 are supported.

See the Docker recipe for detailed usage, CI/CD examples, and limitations.

Package managers

These methods are convenient but may be managed by the community or experience slight publishing delays. If you use Homebrew or Cargo, it is crucial to run mago self-update immediately after installation.

Composer (PHP project)

To add Mago as a development dependency to your PHP project via Composer:

composer require --dev "carthage-software/mago:^1.19.0"

Homebrew (macOS)

:::warning The Homebrew formula for Mago is community-managed and often lags significantly behind official releases. This method is not recommended unless you follow it with a self-update. :::

1. Install the potentially outdated version from Homebrew:

   brew install mago
   

2. Immediately run mago self-update to get the latest official version:

   mago self-update
   

Cargo (Rust)

:::info Publishing to crates.io can sometimes be delayed after a new release. :::

1. Install from Crates.io:

   cargo install mago
   

2. Run mago self-update to ensure you have the absolute latest version:

   mago self-update
   

Verify installation

Once installed, you can verify that Mago is working correctly by checking its version:

mago --version