ommv0.2.148

macOS에 omm 설치하기

Terminal에서 명령 하나면 끝입니다. 먼저 읽어 둘 만한 부분은 Python 요구 사항입니다. macOS에 기본 탑재된 Python은 대개 버전이 너무 낮고, 설치 스크립트가 이를 대신 바꿔 주지는 않습니다.

01 / 08 · macOS

Terminal 열기

어떤 터미널 애플리케이션을 써도 상관없습니다. 명령은 sh에서 실행되므로 로그인 셸이 zsh든 bash든 fish든 결과는 같습니다.

  • Command와 Space를 함께 누르고 Terminal을 입력한 뒤 Enter를 누르세요. Terminal은 Applications › Utilities에서도 찾을 수 있습니다.

  • iTerm2, Warp, Ghostty, 또는 에디터에 내장된 터미널을 써도 모두 괜찮습니다.

  • omm을 설치하는 데 sudo는 필요 없습니다.

프롬프트를 보면 지금 어떤 셸에 있는지 알 수 있습니다. 아래 어느 쪽이든 상관없습니다.

  • you@Mac ~ %zsh — macOS 기본 셸
  • you@Mac:~$bash
  • $sh 또는 기호만 있는 프롬프트
  • omm은 macOS에서 Apple Silicon과 Intel 양쪽 모두 Python 3.10+ 기준으로 CI 테스트를 거칩니다.

02 / 08 · macOS

시작하기 전에

설치 스크립트는 빠진 부분을 Homebrew로 채워 넣습니다. Homebrew 자체가 없다면 Homebrew의 공식 설치 프로그램으로 Homebrew부터 부트스트랩합니다(직접 Homebrew를 설치해 두고 싶다면 먼저 OMM_AUTO_INSTALL_HOMEBREW=0을 export하세요).

  • Python 3.10+
    macOS에 기본 포함된 python3는 대개 3.10보다 낮습니다. Python 3.10+를 찾지 못하면 설치 스크립트가 Homebrew로 설치합니다 — 필요하면 Homebrew 자체도 먼저 부트스트랩합니다.
  • git
    macOS에는 처음 실행하면 Apple의 Command Line Tools 설치 프로그램을 띄우는 git 스텁이 들어 있습니다. 그 대화상자를 수락하는 것만으로 이 요구 사항은 충족됩니다. 그래도 git이 없다면 설치 스크립트가 Python과 같은 방식으로 Homebrew를 통해 git을 설치합니다.
  • pipx
    설치 스크립트는 방금 검증을 마친 그 Python으로 pipx까지 대신 설치합니다. Homebrew나 PEP 668 Python이 일반 --user 설치를 거부하면 --break-system-packages를 붙여 재시도합니다.

03 / 08 · macOS

설치

이 명령을 Terminal에 붙여넣고 Enter를 누르세요.

$ curl -fsSL https://omm.run/install.sh | sh
  • curl이 스크립트를 내려받고 sh가 이를 실행합니다. pipx를 통해 omm을 격리된 CLI로 설치합니다.
  • 설치 후에는 새 셸을 열어야 PATH에 omm이 반영됩니다.
  • -f와 -s 플래그는 실패 시 curl을 조용하게 만듭니다. 아무 반응도 없다면 아래 문제 해결 섹션을 확인하세요.

또는 Homebrew Tap으로 설치

omm은 Homebrew Tap도 제공합니다. 이 Mac에서 이미 Homebrew로 명령줄 도구를 관리하고 있다면 이 방법이 더 편합니다.

macOS · Homebrew Tap

$ brew install omm-hippo/omm/omm

Homebrew로 포뮬러를 업그레이드하거나 제거

$ brew upgrade omm-hippo/omm/omm
$ brew uninstall omm-hippo/omm/omm
  • 포뮬러를 제거해도 OMM_HOME 아래의 다운로드된 모델과 설정은 그대로 남습니다.
  • Homebrew 포뮬러와 PyPI 패키지는 릴리스 일정이 서로 다를 수 있습니다. brew info omm-hippo/omm/omm으로 Tap이 지금 제공하는 버전을 확인하세요.
  • omm update는 Homebrew로 설치한 경우 아무것도 바꾸지 않고, 대신 해당하는 brew upgrade 명령만 출력합니다.

또는 패키지로 설치

PyPI를 통한 일반 패키지 설치도 가능합니다. 위 설치 스크립트가 수행하는 서명된 커밋 검증은 건너뛰며, 이미 Python 도구를 직접 관리하고 있다면 이 방법이 더 맞을 수 있습니다.

$ python -m pip install omm-model

격리된 명령줄 설치를 원한다면 pipx를 권장합니다

$ pipx install omm-model
  • 배포 이름은 omm-model이지만, 설치되는 명령과 Python import는 그대로 omm입니다.
  • 설치할 때 쓴 도구로 그대로 업그레이드하거나 제거하세요: python -m pip install --upgrade omm-model 또는 pipx upgrade omm-model. 둘 다 OMM_HOME 아래의 다운로드된 모델과 설정을 그대로 보존합니다.
  • 이 방법은 앞서 설명한 서명된 커밋 검증을 거치지 않고, PyPI 자체의 계정 보안과 TLS에 의존합니다. 다른 PyPI 패키지를 설치할 때와 다르지 않은 신뢰 모델입니다.
  • omm update는 정식 omm Git 소스 설치만 업데이트합니다. pip나 pipx로 설치했다면 아무것도 바꾸지 않고 해당하는 패키지 매니저 명령만 출력합니다. Git 전용 베타 채널도 패키지 매니저로 설치한 경우에는 쓸 수 없습니다.

04 / 08 · macOS

설치 스크립트가 하는 일

한 줄짜리 설치 스크립트는 그냥 내려받아 실행하는 게 아닙니다. 세 단계를 순서대로 거치며, 가져온 코드가 omm이 서명한 코드와 다르면 두 번째 단계에서 곧바로 멈춥니다.

  1. 스테이징 클론 — 릴리스는 버전이 붙은 스테이징 디렉터리에 클론되며, 지금 실행 중인 사본을 덮어쓰는 일은 없습니다.
  2. 서명된 커밋 검증 — 스테이징된 커밋은 어느 부분이든 실행되기 전에 부트스트랩 신뢰 앵커와 먼저 대조해 검증합니다.
  3. pipx 전환 — 이 검증을 통과한 뒤에야 pipx가 스테이징된 트리로 전환하므로, omm은 계속 격리된 CLI로 남습니다.

커밋의 진위가 중요하다면 이 과정을 검증 없는 git clone과 pipx install로 대체하지 마세요.

05 / 08 · macOS

설치한 다음

설치 스크립트의 마지막 줄은 Done.입니다. 그런데도 'omm' isn't found가 뜬다면 새 셸을 여세요. pipx가 방금 PATH를 갱신했을 뿐이니, 말 그대로 창만 새로 열면 됩니다.

  1. 새 터미널 창 열기

    pipx가 bin 디렉터리를 PATH에 추가하긴 했지만, 이미 실행 중이던 셸은 시작할 때의 PATH를 그대로 유지합니다. 새 창이나 탭이면 충분합니다.

  2. omm을 한 번 실행하기

    막 설치를 마친 상태에서 인자 없이 omm만 실행하면 설정 마법사가 시작됩니다. 하드웨어 요약이 먼저 나오고, 이어서 로컬 AI 러너 체크리스트가 뜹니다. omm이 macOS에서 설치할 수 있는 항목을 체크하면 실시간 진행 상황과 함께 공식 설치 프로그램이 실행되고, 자동으로 설치할 수 없는 항목을 체크하면 대신 다운로드 링크가 출력됩니다. omm setup으로 언제든 다시 실행할 수 있습니다.

    $ omm

  3. omm이 인식하는 내용 확인하기

    omm scan은 앞으로의 모든 적합성 판단이 근거로 삼을 하드웨어, 러너, 모델 요약을 출력합니다.

    $ omm scan

omm scan이 출력하는 항목

  • OS
  • CPU
  • RAM (total)
  • RAM (available)
  • Safe model budget now
  • Reserved for apps/OS
  • GPU
  • VRAM
  • 로컬 AI 러너 — 러너마다 한 행씩, 상태와 함께 표시

06 / 08 · macOS

macOS의 러너

omm은 모델마다 중앙에 사본 하나만 두고, 이를 찾아낸 모든 러너에 링크합니다. 설정 마법사는 이 러너 중 일부를 대신 설치해 주는데, 어떤 것이 가능한지는 운영체제에 따라 갈립니다. 각 제조사가 공식 지원하는 패키지만 쓰기 때문입니다. 세 운영체제 중에서는 macOS의 지원 범위가 가장 넓습니다.

  • Ollama자동 설치
  • LM Studio자동 설치 — headless lms CLI
  • Jan자동 설치 — Homebrew cask
  • AnythingLLM자동 설치 — Homebrew cask
  • Msty자동 설치 — Homebrew cask
  • KoboldCppApple Silicon에서는 자동 설치, Intel Mac은 수동
  • text-generation-webui모든 Mac에서 자동 설치
  • Homebrew를 쓰는 세 행은 Homebrew가 설치돼 있어야 동작합니다. 없으면 마법사는 Homebrew not found - install manually from …라고 알려 주고, 다운로드 URL을 짐작하는 대신 제조사 링크를 그대로 제공합니다.
  • KoboldCpp는 Intel Mac용 빌드를 내놓지 않으므로, Intel Mac에서는 마법사가 설치 대신 다운로드 페이지를 보여 줍니다.
  • 이미 설치된 러너도 마법사 목록에 빠짐없이 나타납니다. 숨기지 않고 installed로 표시하므로, 체크리스트는 항상 omm이 실제로 감지한 상태를 그대로 반영합니다.

07 / 08 · macOS

저장 위치, 자동 완성, 제거

모델이 저장되는 위치

모델 허브와 omm 자체 상태는 기본적으로 ~/.omm에 저장됩니다. 다른 볼륨에 두려면 설치 전과 이후 실행 시 모두 OMM_HOME을 설정하세요. 홈 파일시스템에 GGUF 파일을 담을 여유 공간이 부족할 때 특히 유용합니다.

$ export OMM_HOME=/mnt/models/omm
  • 이 줄을 셸 프로필에 넣어 두면 다음 실행에도 그대로 적용됩니다. macOS의 외장 볼륨은 /Volumes 아래에 있습니다.
  • Ollama 자체의 모델 위치는 OLLAMA_MODELS를 따릅니다. LM Studio는 자체 home 포인터를 따르므로, LM Studio가 omm이 찾을 수 없는 사용자 지정 디렉터리를 쓰고 있다면 OMM_LMSTUDIO_MODELS_DIR을 설정하세요.

셸 자동 완성

셸 자동 완성은 한 번만 설치하면 됩니다. 설치 후 셸을 재시작하세요. bash와 fish도 같은 방식으로 지원됩니다.

$ omm --install-completion zsh

제거

이 작업은 omm 명령과, 설치 스크립트가 관리하던 소스 체크아웃을 제거합니다. OMM_HOME 아래의 다운로드된 모델과 설정은 그대로 남습니다.

$ curl -fsSL https://omm.run/uninstall.sh | sh
  • 모델 허브와 설정까지 함께 지우려면 스크립트를 내려받아 --purge와 함께 실행하세요. Purge는 omm 소유로 확인된 경로만 지우고, 사용자 지정 OMM_HOME 안의 무관한 파일은 건드리지 않습니다.
  • 설치 스크립트는 사용자 지정 홈 디렉터리에 표시를 남겨 두어, 제거 스크립트가 모호하거나 안전하지 않은 위치는 건드리지 않고 거부할 수 있게 합니다. 제거하는 동안 셸 프로필을 다시 쓰는 일은 절대 없습니다.
  • PyPI로 설치했다면 대신 python -m pip uninstall omm-model 또는 pipx uninstall omm-model을 쓰세요. 둘 다 모델과 설정을 보존합니다.

08 / 08 · macOS

문제가 생겼다면

아래 메시지는 모두 설치 스크립트, 제거 스크립트, 셸이 실제로 출력하는 것들입니다. 해당하는 메시지를 찾아 원인을 읽고, 마지막 줄대로 하면 됩니다.

  1. 아무 일도 일어나지 않습니다. 명령이 곧바로 끝나 버리고 omm은 나타나지 않습니다.
    원인
    curl -fsSL은 일부러 조용합니다: -s는 진행 상황과 오류를 숨기고, -f는 HTTP 오류가 나도 조용히 종료시킵니다. 그래서 네트워크가 막혀 있거나 프록시를 거치는 경우, 겉으로는 아무 일도 없는 것처럼 보입니다.
    대처
    스크립트만 따로 먼저 내려받아 오류를 확인한 뒤 실행하세요: curl -fL https://omm.run/install.sh -o install.sh && sh install.sh
    출처
    README, Install section — the curl flags in the command itself
  2. Python 3.10+ not found after dependency bootstrap: https://www.python.org/downloads/
    원인
    Python 3.10+를 찾지 못했고, 설치 스크립트 자체의 Homebrew 기반 부트스트랩도 이를 채우지 못했습니다 — 대개 Homebrew 자체 설치가 실패한 경우입니다.
    대처
    python.org나 Homebrew로 Python 3.10 이상을 설치한 뒤, 새 터미널 창을 열고 설치 명령을 다시 실행하세요.
    출처
    install.sh:272
  3. git not found after dependency bootstrap (needed to fetch omm from GitHub).
    원인
    omm은 검증된 Git 체크아웃으로부터 설치되는데, 설치 스크립트가 Homebrew로 git 설치를 시도한 뒤에도 쓸 수 있는 git을 찾지 못했습니다.
    대처
    xcode-select --install을 실행해 끝날 때까지 기다린 뒤 설치 명령을 다시 실행하세요. macOS가 자체적으로 Command Line Tools 대화상자를 띄웠다면 그걸 수락해도 같은 효과입니다.
    출처
    install.sh:277
  4. git 2.34+ is required to verify SSH commit signatures (found git version 2.30.0).
    원인
    git 버전이 너무 오래되어 SSH 커밋 서명을 확인할 수 없습니다. 설치 스크립트는 이런 '검증 불가' 상태를 서명 오류와 똑같이 취급합니다.
    대처
    git을 업데이트하세요 — brew install git을 실행하거나 Command Line Tools를 다시 설치한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:81
  5. Homebrew installation failed. Install it manually from https://brew.sh/ and rerun this installer.
    원인
    Homebrew 자체를 자동으로 설치하지 못했습니다 — Homebrew의 자체 설치 프로그램이 실패했거나, 부트스트랩에 필요한 curl·/bin/bash를 쓸 수 없었던 경우입니다. Homebrew가 없는 상태에서 OMM_AUTO_INSTALL_HOMEBREW=0을 설정해도 같은 벽에 부딪힙니다.
    대처
    https://brew.sh/ 에서 Homebrew를 직접 설치하거나, OMM_AUTO_INSTALL_HOMEBREW를 unset한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:205
  6. Signature verification failed - refusing to install untrusted code.
    원인
    스테이징된 커밋이 설치 스크립트의 신뢰 앵커에 등록된 키로 서명되지 않았거나, 앞 항목처럼 git이 서명 자체를 확인하지 못한 경우입니다.
    대처
    git을 업데이트한 뒤 다시 시도하세요. 그래도 실패한다면 일반 git clone으로 우회하지 말고, 대신 저장소에 이슈를 등록하세요.
    출처
    install.sh:596
  7. error: externally-managed-environment
    원인
    Homebrew 등 PEP 668 Python은 일반 pip 설치를 거부합니다. 설치 스크립트는 이 상황을 이미 예상하고 있어서, pipx 자체 설치를 --break-system-packages와 함께 재시도합니다.
    대처
    이 단계를 지나 설치가 계속된다면 따로 할 일은 없습니다. 여기서 멈췄다면 pipx를 직접 설치하고(brew install pipx && pipx ensurepath) 설치 명령을 다시 실행하세요.
    출처
    install.sh:513-519
  8. Could not inspect existing pipx environments; refusing an unsafe migration.
    원인
    pipx list --json이 쓸 수 있는 출력을 내놓지 못해서, 설치 스크립트는 자신이 무엇을 대체하게 될지 알 방법이 없습니다. 짐작하는 대신 그냥 멈춥니다.
    대처
    pipx가 단독으로 잘 실행되는지 확인하고(python3 -m pipx list), 안 된다면 복구한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:543
  9. Refusing to replace unrelated pipx environment 'omm'. Remove or rename that environment manually first.
    원인
    omm이라는 이름의 무관한 다른 PyPI 프로젝트가 이미 그 pipx 환경을 쓰고 있습니다. 설치 스크립트는 남의 도구를 덮어쓰지 않습니다.
    대처
    그 다른 도구가 필요 없다면 pipx uninstall omm을 실행하거나 해당 환경의 이름을 바꾼 뒤, 설치 명령을 다시 실행하세요.
    출처
    install.sh:551
  10. Refusing to replace an unverified omm-model pipx environment.
    원인
    omm-model이라는 pipx 환경은 있지만, omm이 만든 것으로 보이지 않습니다.
    대처
    pipx uninstall omm-model을 실행한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:561
  11. zsh: command not found: omm
    원인
    설치는 끝났지만, 이 셸은 여전히 시작할 때의 PATH를 그대로 갖고 있습니다.
    대처
    새 터미널 창을 여세요. 설치 스크립트도 마지막 줄에 같은 안내를 출력합니다.
    출처
    install.sh:494-509
  12. Refusing non-absolute OMM_HOME: models/omm
    원인
    OMM_HOME은 절대 경로여야 합니다. Refusing unsafe OMM_HOME이라는 관련 메시지가 뜬다면 /나 홈 디렉터리 자체를 가리키고 있다는 뜻입니다.
    대처
    하위 디렉터리까지 이어지는 전체 경로를 쓰세요. 예: export OMM_HOME=/Volumes/Models/omm.
    출처
    install.sh:11
  13. Homebrew not found - install manually from https://docs.anythingllm.com/installation-desktop/overview
    원인
    이건 설치 스크립트가 아니라 설정 마법사 이야기입니다. Homebrew 기반의 세 러너는 PATH에 brew가 있어야 합니다. omm은 다운로드 URL을 직접 추측하지 않습니다.
    대처
    Homebrew를 설치하고 omm setup을 다시 실행하거나, 출력된 링크에서 해당 러너를 직접 설치하세요 — 어느 쪽이든 omm은 모델을 링크해 줍니다.
    출처
    src/omm/linker.py:2612-2616
  14. Refusing unrecognized custom OMM_HOME (missing .omm-managed): /Volumes/Models/omm
    원인
    설치 스크립트가 한 번도 자신의 것으로 표시한 적 없는 사용자 지정 OMM_HOME에서 제거를 시도하고 있어, 제거 스크립트가 그 폴더를 건드려도 안전한지 확신할 수 없습니다.
    대처
    OMM_HOME이 omm이 실제로 설치된 폴더를 가리키는지 확인한 뒤, 제거 스크립트를 다시 실행하세요.
    출처
    uninstall.sh:42

그래도 해결되지 않는다면, 화면에 뜬 메시지 그대로와 omm scan 출력을 함께 첨부해 이슈를 등록하세요.