Installation¶

gmlx installs with Homebrew, or with uv or pip when you want to choose its optional features.

Requirements¶

gmlx needs an Apple Silicon Mac, and it does not run on Intel Macs or Linux. The model you can run depends on the Mac's memory, as Choosing a model shows.
It needs macOS 26.2 or newer, because the mlx-kquant Metal kernels are built for it and install prebuilt.
The models need several GB of disk space each.

Homebrew¶

Install with Homebrew:

brew install asher/gmlx/gmlx

The formula installs gmlx with every optional feature, and ffmpeg for voice and audio. It installs the exact dependency versions that were tested with its release, in an environment of its own, so there is no Python setup to do.

uv¶

To choose the optional features yourself, install with uv:

brew install uv
uv tool install "gmlx[all]"
brew install ffmpeg

The uv tool puts the gmlx command on your PATH in an isolated environment, and it downloads a suitable Python when your system has none. Voice, speech-to-text on the server, and speech output in a format other than WAV or PCM need ffmpeg.

pip¶

To use gmlx from a Python environment that you manage, for example to call its Python API, install it with pip in that environment. It needs Python 3.11 or newer.

python3 -m venv .venv
source .venv/bin/activate
pip install "gmlx[all]"

The gmlx command then exists only while the environment is active. If a new terminal cannot find gmlx, activate the environment again, as Troubleshooting describes.

Optional features¶

The core install serves models, loads vision models, computes embeddings and runs the menu bar app. Each extra adds one of the other features, and the Homebrew formula includes all of them.

Extra	What it adds
`chat`	It adds a completion menu, a toolbar and rich markdown rendering to `gmlx chat`.
`stt`	It adds speech-to-text to the server, with mlx-whisper.
`tts`	It adds text-to-speech to the server, with the Kokoro phoneme front end.
`talk`	It adds the voice client, `gmlx talk`, and includes `stt` and `tts`.
`assistant`	It adds MCP tools to the built-in assistant.
`all`	It includes every extra in this list.

To add an extra to a uv install later, name every extra you want in one command, because uv replaces the install with exactly what the command lists:

uv tool install --force "gmlx[chat,talk]"

With pip, run pip install "gmlx[talk]" in the same environment. The command keeps the extras that are already there. When you turn on speech in gmlx init, it offers to install the extras that speech needs. A message that says a feature is not installed also gives the command for your kind of install.

Tab completion¶

gmlx completes its commands, flags, your model ids and the ports of running servers. For zsh, add this line to ~/.zshrc:

eval "$(gmlx completion zsh)"

For bash, add eval "$(gmlx completion bash)" to ~/.bashrc. For fish, add gmlx completion fish | source to ~/.config/fish/config.fish.

Upgrading¶

Upgrade with the tool that installed gmlx:

Install	Upgrade command
Homebrew	`brew upgrade gmlx`
uv	`uv tool upgrade gmlx`
pip	`pip install -U gmlx` in its environment

A server that is running during an upgrade keeps the old code until you run gmlx restart. A server installed as a login item with --headless is restarted by launchd instead, and gmlx restart prints the launchctl command that does it.

Removing gmlx¶

To remove gmlx completely:

If you installed the login item, run gmlx service uninstall.
Uninstall the package with the tool that installed it, which is brew uninstall gmlx, uv tool uninstall gmlx, or pip uninstall gmlx mlx-kquant in its environment.
Delete the files that gmlx wrote, which Where files are on disk lists, and the models you downloaded.

Steps 1 and 2 leave your configuration, caches and models in place, so a later install finds them again.