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

시작하기 전에

설치 스크립트의 자동 의존성 설치는 apt를 사용하는데, macOS에는 apt가 없습니다. 따라서 Mac에서는 Python과 git이 이미 준비되어 있다고 가정합니다.

  • Python 3.10+
    필수이며, 대개 여기서 문제가 생깁니다. macOS에 기본 포함된 python3는 대부분의 시스템에서 3.10보다 낮은 버전입니다. 설치 스크립트를 실행하기 전에 python.org에서 최신 Python을 설치하거나 Homebrew로 설치하세요.
  • git
    필수입니다. macOS에는 처음 실행할 때 Apple의 Command Line Tools 설치 프로그램을 여는 git 스텁이 포함되어 있습니다. 그 대화상자를 수락하거나, xcode-select --install을 직접 실행하세요.
  • pipx
    설치 스크립트는 검증을 마친 바로 그 Python을 통해 pipx를 대신 설치합니다. Homebrew나 PEP 668 Python이 일반 --user 설치를 거부하면 --break-system-packages를 붙여 재시도합니다.

03 / 08 · macOS

설치

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

$ curl -fsSL https://raw.githubusercontent.com/omm-hippo/omm/main/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://raw.githubusercontent.com/omm-hippo/omm/main/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://raw.githubusercontent.com/omm-hippo/omm/main/install.sh -o install.sh && sh install.sh
    출처
    README, Install section — the curl flags in the command itself
  2. Python 3.10+ not found: https://www.python.org/downloads/
    원인
    python3나 python 3.10 이상 버전을 찾지 못했습니다. macOS에서는 설치 스크립트가 이를 스스로 해결할 수 없습니다 — 자동 설치는 apt 기반인데 macOS에는 apt가 없기 때문입니다.
    대처
    python.org에서 Python 3.10 이상을 설치하거나 Homebrew로 설치한 뒤, 새 터미널 창을 열고 설치 명령을 다시 실행하세요.
    출처
    install.sh:135
  3. git not found. Install git first (needed to fetch omm from GitHub).
    원인
    omm은 검증된 Git 체크아웃으로부터 설치됩니다. Xcode Command Line Tools가 없는 Mac에는 사용할 수 있는 git이 없습니다.
    대처
    xcode-select --install을 실행해 완료될 때까지 기다린 뒤 설치 명령을 다시 실행하세요. macOS가 자체적으로 Command Line Tools 대화상자를 열었다면, 그것을 수락해도 같은 효과입니다.
    출처
    install.sh:148
  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. Signature verification failed - refusing to install untrusted code.
    원인
    스테이징된 커밋이 설치 스크립트의 신뢰 앵커에 있는 키로 서명되지 않았거나, 앞 항목과 마찬가지로 git이 서명을 아예 확인하지 못한 경우입니다.
    대처
    git을 업데이트한 뒤 다시 시도하세요. 그래도 실패한다면 일반 git clone으로 우회하지 말고, 대신 저장소에 이슈를 등록하세요.
    출처
    install.sh:396
  6. error: externally-managed-environment
    원인
    Homebrew 등 PEP 668 Python은 일반 pip 설치를 거부합니다. 설치 스크립트는 이를 이미 예상하고 있으며, pipx 자체 설치를 --break-system-packages와 함께 재시도합니다.
    대처
    이 단계를 넘어가며 설치가 계속된다면 별도로 할 일은 없습니다. 여기서 멈춘다면 직접 pipx를 설치하고(brew install pipx && pipx ensurepath) 설치 명령을 다시 실행하세요.
    출처
    install.sh:327-336
  7. Could not inspect existing pipx environments; refusing an unsafe migration.
    원인
    pipx list --json이 사용 가능한 출력을 반환하지 않아, 설치 스크립트는 무엇을 대체하게 될지 판단할 수 없습니다. 추측하는 대신 중단합니다.
    대처
    pipx가 단독으로 실행되는지 확인하고(python3 -m pipx list), 안 된다면 복구한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:343
  8. Refusing to replace unrelated pipx environment 'omm'. Remove or rename that environment manually first.
    원인
    omm이라는 이름의 무관한 다른 PyPI 프로젝트가 이미 해당 pipx 환경을 점유하고 있습니다. 설치 스크립트는 다른 도구를 덮어쓰지 않습니다.
    대처
    그 다른 도구가 필요 없다면 pipx uninstall omm을 실행하거나 해당 환경의 이름을 변경한 뒤, 설치 명령을 다시 실행하세요.
    출처
    install.sh:351
  9. Refusing to replace an unverified omm-model pipx environment.
    원인
    omm-model pipx 환경이 존재하지만 omm이 생성한 것으로 보이지 않습니다.
    대처
    pipx uninstall omm-model을 실행한 뒤 설치 명령을 다시 실행하세요.
    출처
    install.sh:361
  10. zsh: command not found: omm
    원인
    설치는 끝났지만 이 셸은 여전히 시작할 때의 PATH를 그대로 가지고 있습니다.
    대처
    새 터미널 창을 여세요. 설치 스크립트도 마지막 줄에 같은 안내를 출력합니다.
    출처
    install.sh:508
  11. Refusing non-absolute OMM_HOME: models/omm
    원인
    OMM_HOME은 절대 경로여야 합니다. 관련 메시지인 Refusing unsafe OMM_HOME이 나타나면 /나 홈 디렉터리 자체를 가리키고 있다는 뜻입니다.
    대처
    하위 디렉터리로 이어지는 전체 경로를 사용하세요. 예: export OMM_HOME=/Volumes/Models/omm.
    출처
    install.sh:11 and install.sh:14
  12. 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:2104-2108
  13. Refusing unrecognized custom OMM_HOME (missing .omm-managed): /Volumes/Models/omm
    원인
    설치 스크립트가 자신의 것으로 표시한 적 없는 사용자 지정 OMM_HOME으로 제거를 시도하고 있어, 제거 스크립트는 해당 폴더를 건드려도 안전한지 증명할 수 없습니다.
    대처
    OMM_HOME이 omm이 실제로 설치된 폴더를 가리키는지 확인한 뒤, 제거 스크립트를 다시 실행하세요.
    출처
    uninstall.sh:42

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