# How to Install MTPLX on Apple Silicon Macs

> Install MTPLX on Apple Silicon Macs with the official installer script or pip. Learn how to set up this tool quickly and efficiently for your development workflow.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: getting-started
- Published: 2026-09-11

---

**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`](https://github.com/youssofal/MTPLX/blob/main/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:

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

```

After installation completes, verify the setup:

```bash
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`](https://github.com/youssofal/MTPLX/blob/main/INSTALL.md) lines 28-34, this method skips the shell script entirely but installs the same wheels:

```bash
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:

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

```

This installs the package from source along with development and server dependencies defined in [`pyproject.toml`](https://github.com/youssofal/MTPLX/blob/main/pyproject.toml).

## How the Installer Works

The [`install_macos.sh`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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:

```bash
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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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.