Install omm on macOS

One command in Terminal. The part worth reading first is the Python requirement: the version of Python that ships with macOS is usually too old, and the installer will not replace it for you.

01 Which app to open
02 Before you start
03 Install
04 What the installer does
05 After install
06 Runners on this system
07 Storage, completion, uninstall
08 If something goes wrong

01 / 08 · macOS

Open Terminal

Any terminal application works. The command runs under sh, so your login shell being zsh, bash or fish makes no difference.

Press Command and Space, type Terminal, and press Enter. Terminal is also in Applications › Utilities.
iTerm2, Warp, Ghostty, or the terminal built into your editor are all fine.
You do not need sudo to install omm.

The prompt tells you which shell you are in. All of these are fine.

you@Mac ~ %zsh — the macOS default
you@Mac:~$bash
$sh, or a bare prompt

omm is tested in CI on macOS with Python 3.10+, on both Apple Silicon and Intel.

02 / 08 · macOS

Before you start

The installer's automatic dependency bootstrap uses apt, which does not exist on macOS. On a Mac it therefore expects Python and git to already be there.

Python 3.10+
Required, and this is the one that usually bites. The python3 that comes with macOS is older than 3.10 on most systems. Install a current Python from python.org, or with Homebrew, before running the installer.
- python.org/downloads
- brew.sh
git
Required. macOS ships a git stub that opens Apple's Command Line Tools installer the first time you run it; accept that dialog, or run xcode-select --install yourself.
- git-scm.com/downloads
pipx
The installer installs pipx for you through the exact Python it validated, retrying with --break-system-packages when a Homebrew or PEP 668 Python refuses a plain --user install.

03 / 08 · macOS

Install

Paste this into Terminal and press Enter.

$ curl -fsSL https://raw.githubusercontent.com/omm-hippo/omm/main/install.sh | sh

curl downloads the script and sh runs it. It installs omm as an isolated CLI through pipx.
Open a new shell afterward so your PATH picks up omm.
The -f and -s flags make curl silent on failure. If nothing at all happens, see the troubleshooting section below.

Or install from the Homebrew Tap

omm publishes a Homebrew Tap. Use it if Homebrew is already how you manage command-line tools on this Mac.

macOS · Homebrew Tap

$ brew install omm-hippo/omm/omm

Upgrade or remove the formula with Homebrew

$ brew upgrade omm-hippo/omm/omm

$ brew uninstall omm-hippo/omm/omm

Removing the formula preserves downloaded models and settings under OMM_HOME.
The Homebrew formula and PyPI package can move on separate release schedules; use brew info omm-hippo/omm/omm to see the version currently provided by the Tap.
omm update does not modify a Homebrew installation and instead prints the matching brew upgrade command.

Or install the package

There is also a plain package install from PyPI. It skips the signed-commit check that the script above performs, and it is the right choice if you already manage your Python tooling.

$ python -m pip install omm-model

For an isolated command-line installation, pipx is recommended

$ pipx install omm-model

The distribution name is omm-model; the installed command and Python import remain omm.
Upgrade and remove it with the same tool that installed it: python -m pip install --upgrade omm-model, or pipx upgrade omm-model. Both preserve downloaded models and settings under OMM_HOME.
This does not go through the signed-commit verification described above; it relies on PyPI's own account security and TLS, the same trust model as installing any other PyPI package.
omm update only updates a canonical omm Git-source installation. On a pip or pipx install it changes nothing and prints the matching package manager command instead. The Git-only beta channel is likewise unavailable to package-managed installations.

04 / 08 · macOS

What the installer does

The one-line installer is not a plain download-and-run. It does three things in order, and it stops at the second one if the code it fetched is not the code omm signed.

staging clone — The release is cloned into a versioned staging directory, never over the copy you are currently running.
signed commit verified — The staged commit is checked against a bootstrap trust anchor before any of it is executed.
pipx switch — Only after that does pipx switch to the staged tree, so omm stays an isolated CLI.

Do not replace this with an unverified git clone plus pipx install if commit authenticity matters to you.

05 / 08 · macOS

After install

The installer's last line is Done. If 'omm' isn't found, open a new shell (pipx just updated your PATH). Take that literally.

open a new terminal window
pipx added its bin directory to your PATH, but a shell that was already running keeps the PATH it started with. A new window or tab is enough.
02
run omm once
A bare omm on a fresh install starts the setup wizard: a hardware summary, then a checklist of local AI runners. Checking one that omm can install on macOS runs its official installer with live progress; checking one it cannot automate here prints a link instead. You can re-run it any time with omm setup.
$ omm
03
check what omm sees
omm scan prints the hardware, runner and model summary it will base every fit decision on.
$ omm scan

omm scan reports

OS
CPU
RAM (total)
RAM (available)
Safe model budget now
Reserved for apps/OS
GPU
VRAM
Local AI runners — one row per runner, with its status

06 / 08 · macOS

Runners on macOS

omm links one central copy of each model into every runner it finds. The setup wizard can install some of those runners for you — which ones depends on the operating system, because it only uses each vendor's own supported package. macOS has the widest coverage of the three.

OllamaAutomated
LM StudioAutomated — headless lms CLI
JanAutomated — Homebrew cask
AnythingLLMAutomated — Homebrew cask
MstyAutomated — Homebrew cask
KoboldCppAutomated on Apple Silicon; Intel Macs are manual
text-generation-webuiAutomated on any Mac

The three Homebrew rows need Homebrew installed. Without it the wizard reports Homebrew not found - install manually from … and gives you the vendor's link rather than guessing at a download URL.
KoboldCpp publishes no Intel Mac build, so on an Intel Mac the wizard prints the download page instead of installing.
Every runner already installed is listed in the wizard too, marked as installed rather than hidden, so the checklist always reflects what omm actually detects.

07 / 08 · macOS

Storage, completion, uninstall

Where models are stored

The model hub and omm's own state default to ~/.omm. Set OMM_HOME before installing, and on later runs, to put them on another volume — useful when your home filesystem does not have room for GGUF files.

$ export OMM_HOME=/mnt/models/omm

Put that line in your shell profile so later runs see it too. An external volume on macOS lives under /Volumes.
Ollama's own model location follows OLLAMA_MODELS. LM Studio follows its home pointer; set OMM_LMSTUDIO_MODELS_DIR when LM Studio uses a custom directory omm cannot discover.

Shell completion

Install tab-completion once, then restart the shell. bash and fish are supported the same way.

$ omm --install-completion zsh

Uninstall

This removes the omm command and the installer-managed source checkouts. Downloaded models and settings under OMM_HOME are preserved.

$ curl -fsSL https://raw.githubusercontent.com/omm-hippo/omm/main/uninstall.sh | sh

To remove the model hub and settings as well, download the script and run it with --purge. Purge removes only known omm-owned paths and leaves unrelated files in a custom OMM_HOME untouched.
Installers mark custom homes so uninstallers can refuse ambiguous or unsafe locations, and shell profiles are never rewritten during uninstall.
If you installed from PyPI instead, use python -m pip uninstall omm-model or pipx uninstall omm-model. Both preserve models and settings.

08 / 08 · macOS

If something goes wrong

Every message below is one the installer, the uninstaller or the shell actually prints. Find yours, read why it happened, then do the last line.

```
Nothing at all. The command returns immediately and no omm appears.
```
why
curl -fsSL is deliberately quiet: -s hides its progress and errors, -f makes it exit silently on an HTTP error. A blocked network or a proxy therefore looks like nothing happening.
what to do
Download the script on its own first so you can read the error, then run it: curl -fL https://raw.githubusercontent.com/omm-hippo/omm/main/install.sh -o install.sh && sh install.sh
source
README, Install section — the curl flags in the command itself
```
Python 3.10+ not found: https://www.python.org/downloads/
```
why
No python3 or python of version 3.10 or newer was found. On macOS the installer cannot fix this itself — its automatic bootstrap is apt-based and apt does not exist here.
what to do
Install Python 3.10 or newer from python.org, or with Homebrew, open a new terminal window, then run the install command again.
source
install.sh:135
```
git not found. Install git first (needed to fetch omm from GitHub).
```
why
omm is installed from a verified Git checkout. On a Mac without the Xcode Command Line Tools there is no usable git.
what to do
Run xcode-select --install, let it finish, then run the install command again. If macOS opened its own Command Line Tools dialog, accepting that has the same effect.
source
install.sh:148
```
git 2.34+ is required to verify SSH commit signatures (found git version 2.30.0).
```
why
Your git is too old to check SSH commit signatures. The installer treats cannot verify exactly like a bad signature.
what to do
Update git — brew install git, or reinstall the Command Line Tools — then run the install command again.
source
install.sh:81
```
Signature verification failed - refusing to install untrusted code.
```
why
The staged commit was not signed by a key in the installer's trust anchor — or git could not check the signature at all, as in the previous entry.
what to do
Update git and retry. If it still fails, do not work around it with a plain git clone: open an issue on the repository instead.
source
install.sh:396
```
error: externally-managed-environment
```
why
A Homebrew or other PEP 668 Python refuses plain pip installs. The installer already expects this and retries pipx's own install with --break-system-packages.
what to do
Nothing, if the install continues past it. If it stops there, install pipx yourself (brew install pipx && pipx ensurepath) and run the install command again.
source
install.sh:327-336
```
Could not inspect existing pipx environments; refusing an unsafe migration.
```
why
pipx list --json did not return usable output, so the installer cannot tell what it would be replacing. It stops instead of guessing.
what to do
Check that pipx runs on its own (python3 -m pipx list), repair it if not, then run the install command again.
source
install.sh:343
```
Refusing to replace unrelated pipx environment 'omm'. Remove or rename that environment manually first.
```
why
An unrelated PyPI project also called omm already owns that pipx environment. The installer will not overwrite someone else's tool.
what to do
Run pipx uninstall omm if you do not need that other tool, or rename its environment, then run the install command again.
source
install.sh:351
```
Refusing to replace an unverified omm-model pipx environment.
```
why
An omm-model pipx environment exists but does not look like one omm created.
what to do
Run pipx uninstall omm-model, then run the install command again.
source
install.sh:361
```
zsh: command not found: omm
```
why
The install finished, but this shell still has the PATH it started with.
what to do
Open a new terminal window. The installer prints the same advice on its last line.
source
install.sh:508
```
Refusing non-absolute OMM_HOME: models/omm
```
why
OMM_HOME has to be an absolute path. A sibling message, Refusing unsafe OMM_HOME, means it points at / or at your home directory itself.
what to do
Use a full path to a subdirectory, for example export OMM_HOME=/Volumes/Models/omm.
source
install.sh:11 and install.sh:14
```
Homebrew not found - install manually from https://docs.anythingllm.com/installation-desktop/overview
```
why
This is the setup wizard, not the installer: the three Homebrew-based runners need brew on PATH. omm never guesses a direct download URL.
what to do
Install Homebrew and re-run omm setup, or install that runner yourself from the printed link — omm links models into it either way.
source
src/omm/linker.py:2104-2108
```
Refusing unrecognized custom OMM_HOME (missing .omm-managed): /Volumes/Models/omm
```
why
You are uninstalling with a custom OMM_HOME that the installer never marked as its own, so the uninstaller cannot prove the folder is safe to touch.
what to do
Check that OMM_HOME points at the folder omm actually installed into, then run the uninstaller again.
source
uninstall.sh:42

Still stuck? Open an issue with the exact message you saw and the output of omm scan.