How to Install MTPLX on Apple Silicon Macs

Install MTPLX on Apple Silicon Macs by running the official installer script that validates your environment, creates an isolated virtual environment at ~/.mtplx/venv, and provisions a launcher in ~/.local/bin, or alternatively use pip install mtplx for a pure-Python setup.

MTPLX is a native macOS application and command-line tool for running large language models with multi-token prediction (MTP) using Apple's MLX framework. According to the youssofal/MTPLX source code, the installation process requires an Apple Silicon (ARM64) Mac running macOS 14 or newer with Python 3.11+ available. The installation is designed to be non-intrusive, avoiding modifications to Homebrew's Cellar while ensuring the mtplx command is available across new terminal sessions.

System Requirements

Hardware and Operating System

MTPLX depends on Apple's MLX framework, which is optimized for ARM64 architecture. The installer performs strict environment validation before proceeding. In scripts/install_macos.sh lines 67-71, the script checks that uname -s returns Darwin and uname -m returns arm64, ensuring you are running on Apple Silicon. The tool requires macOS 14 or newer.

Python Version

You must have Python 3.11 or newer installed. The installer searches for a compatible interpreter in Homebrew locations, /usr/local/bin, and your system PATH. If no suitable Python version is found, the script aborts with a clear error message. You can verify your Python version with python3 --version before starting.

Installation Methods

Method 1: Official Installer Script (Recommended)

The fastest way to install MTPLX uses the official macOS installer script. This approach handles environment validation, dependency isolation, and shell integration automatically.

Run the following command in your terminal:

curl -fsSL https://raw.githubusercontent.com/youssofal/MTPLX/main/scripts/install_macos.sh | bash

After installation completes, verify the setup:

mtplx --version
mtplx help

Method 2: Pure-Python pip Install

For development environments, CI pipelines, or when you prefer manual control, install MTPLX directly from PyPI. As documented in INSTALL.md lines 28-34, this method skips the shell script entirely but installs the same wheels:

python3 -m pip install -U mtplx

This command installs the mtplx package globally or in your current virtual environment. Both the script-based and pip-only approaches yield identical runtime behavior.

Method 3: Development Install

To install MTPLX in editable mode for local development, clone the repository and install with extras:

python -m pip install -e ".[dev,server]"

This installs the package from source along with development and server dependencies defined in pyproject.toml.

How the Installer Works

The install_macos.sh script implements a three-layer installation process designed to be non-intrusive and reversible.

Step 1: Environment Validation

Before modifying your system, the script validates the platform. As implemented in scripts/install_macos.sh lines 67-71, it verifies that you are running on Darwin (macOS) with ARM64 architecture. It then locates a suitable Python 3.11+ interpreter. If validation fails, the script exits immediately without making changes.

Step 2: Virtual-Environment Bootstrap

The installer creates a dedicated virtual environment at ~/.mtplx/venv. According to lines 30-33 in install_macos.sh, the script upgrades pip inside this environment and installs the mtplx package from PyPI. You can override the package source by setting the MTPLX_PACKAGE_SPEC environment variable before running the installer.

Step 3: Launcher Provisioning

The script creates a durable wrapper script at ~/.local/bin/mtplx. This wrapper activates the virtual environment and forwards all arguments to the installed binary. As shown in lines 34-46 of install_macos.sh, the script also appends ~/.local/bin to your shell startup files (.zprofile, .zshrc, or .bash_profile) if not already present.

Optionally, you can specify a global launcher location via the MTPLX_GLOBAL_BIN environment variable. The installer only creates this symlink if the target does not exist or contains a marker comment indicating it was previously created by MTPLX (lines 27-53). This safety mechanism prevents overwriting existing Homebrew binaries.

Post-Installation Configuration

If you skipped the shell script modification or installed via pip, manually add the launcher to your PATH:

export PATH="$HOME/.local/bin:$PATH"
mtplx start

To make this permanent, add the export line to your shell configuration file (.zshrc, .bash_profile, or .zprofile).

Summary

• How to install MTPLX requires an Apple Silicon Mac running macOS 14+ with Python 3.11+.
• The official installer script at scripts/install_macos.sh validates your environment, creates an isolated virtual environment at ~/.mtplx/venv, and installs a launcher at ~/.local/bin/mtplx.
• Alternative installation uses python3 -m pip install -U mtplx for pure-Python setups or pip install -e ".[dev,server]" for development.
• The installer modifies shell startup files to persist the PATH change but never overwrites existing binaries outside its managed directory.
• Verify installation success by running mtplx --version and mtplx help.

Frequently Asked Questions

Can I install MTPLX on an Intel Mac?

No. According to the source code in install_macos.sh lines 67-71, the installer explicitly checks for ARM64 architecture (uname -m = arm64) because MTPLX depends on Apple's MLX framework, which requires Apple Silicon. The installation will abort on Intel-based Macs.

What happens if the installer cannot find Python 3.11?

The script will abort with a clear error message before making any system changes. You must install Python 3.11 or newer manually—preferably via Homebrew or python.org—and ensure it is available in your PATH before retrying the installation.

Does the installer modify my shell configuration files?

Yes. The installer appends ~/.local/bin to your PATH by modifying .zprofile, .zshrc, or .bash_profile (depending on which files exist), but only if the directory is not already present. It will not duplicate entries or modify files unrelated to shell initialization.

How do I uninstall MTPLX?

To completely remove MTPLX, delete the virtual environment directory at ~/.mtplx/, remove the launcher script at ~/.local/bin/mtplx, and delete any global symlinks you created via MTPLX_GLOBAL_BIN. Finally, edit your shell configuration files to remove the export PATH="$HOME/.local/bin:$PATH" line if it was added by the installer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}