Linux에 omm 설치하기

01 / 08 · Linux

터미널 열기

어떤 터미널 에뮬레이터를 사용해도 됩니다 — GNOME Terminal, Konsole, xterm, Alacritty. 명령은 sh에서 실행되므로, 로그인 셸이 bash든 zsh든 fish든 상관없습니다.

• 대부분의 데스크톱에서는 Ctrl, Alt, T를 함께 눌러 터미널을 엽니다.

• 그렇지 않다면 애플리케이션 메뉴에서 Terminal, Konsole 또는 Console을 찾으세요.

• root일 필요는 없습니다. 설치 스크립트는 apt로 패키지를 설치해야 할 때만 sudo를 요청합니다.

프롬프트를 보면 어떤 셸에 있는지 알 수 있습니다. 아래 모두 사용해도 괜찮습니다.

• you@host:~$bash — 일반적인 기본 셸
• you@host ~ %zsh
• root@host:~#root 셸 — 이것도 괜찮습니다

• omm은 Linux에서 Python 3.10+로 CI 테스트를 거칩니다.

02 / 08 · Linux

시작하기 전에

설치 스크립트의 자동 의존성 설치는 apt에서만 동작합니다. Debian과 Ubuntu에서는 필요한 모든 것을 설치할 수 있고, 그 외에서는 설치 대신 확인하고 알려주기만 합니다.

• Python 3.10+

  필수입니다. apt가 있는 시스템에서는 python3가 없으면 설치 스크립트가 apt-get install python3 python3-venv python3-pip를 실행합니다. 그 외에는 먼저 직접 설치하세요.

  • python.org/downloads
• git

  필수입니다. omm은 검증된 Git 체크아웃으로부터 설치되기 때문입니다. apt가 있으면 설치 스크립트가 git과 ca-certificates를 대신 추가합니다.

  • git-scm.com/downloads
• python3-venv

  pipx가 필요로 하며, Debian과 Ubuntu에서는 별도 패키지로 제공됩니다. 없으면 pipx가 알기 힘든 ensurepip is not available 오류로 실패하므로, 설치 스크립트가 이를 명시적으로 먼저 설치합니다.
• Fedora, Arch, openSUSE, Alpine

  apt가 없으므로 자동 설치도 없습니다. 사용 중인 패키지 매니저로 Python 3.10+와 git을 먼저 설치하세요 — 예를 들어 sudo dnf install python3 git 또는 sudo pacman -S python git.
• root or sudo

  apt 단계는 root로 직접 실행되거나, 가능하다면 sudo를 통해 실행됩니다. 둘 다 없으면 이 단계는 건너뛰고, 설치 스크립트는 대신 누락된 의존성을 알려줍니다.

03 / 08 · Linux

설치

이것을 터미널에 붙여넣고 Enter를 누르세요.

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

• curl이 스크립트를 다운로드하고 sh가 이를 실행합니다. pipx를 통해 omm을 격리된 CLI로 설치합니다.
• 이후 새 셸을 열어야 PATH가 omm을 인식합니다.
• -f와 -s 플래그는 실패 시 curl을 조용하게 만듭니다. 아무 일도 일어나지 않는다면 아래 문제 해결 섹션을 참고하세요.

$ python -m pip install omm-model

$ pipx install omm-model

04 / 08 · Linux

설치 스크립트가 하는 일

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

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

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

05 / 08 · Linux

설치한 다음

설치 스크립트의 마지막 줄은 Done.입니다. 'omm' isn't found가 나타나면 새 셸을 여세요(pipx가 방금 PATH를 갱신했습니다). 말 그대로입니다.

1. 01

   새 셸 열기

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

2. 02

   omm을 한 번 실행하기

   방금 설치한 상태에서 인자 없이 omm을 실행하면 설정 마법사가 시작됩니다: 하드웨어 요약에 이어 로컬 AI 러너 체크리스트가 나타납니다. omm이 Linux에서 설치할 수 있는 항목을 체크하면 실시간 진행 상황과 함께 공식 설치 프로그램이 실행되고, 여기서 자동으로 설치할 수 없는 항목을 체크하면 대신 링크가 출력됩니다. omm setup으로 언제든 다시 실행할 수 있습니다.

   $ omm

   복사
3. 03

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

   omm scan은 모든 적합성 판단의 근거가 되는 하드웨어, 러너, 모델 요약을 출력합니다.

   $ omm scan

   복사

06 / 08 · Linux

Linux의 러너

omm은 각 모델을 중앙에 하나만 보관하고 이를 발견한 모든 러너에 링크합니다. 설정 마법사는 이 러너 중 일부를 대신 설치해 줄 수 있는데, 어떤 것이 가능한지는 운영체제에 따라 다릅니다. 각 제조사가 공식적으로 지원하는 패키지만 사용하기 때문입니다.

• Ollama자동 설치
• LM Studio자동 설치 — headless lms CLI
• Jan자동 설치 — Flatpak
• KoboldCppx86_64에서 자동 설치
• text-generation-webuix86_64에서 자동 설치
• AnythingLLM수동 — 직접 설치하면 omm이 그대로 링크합니다
• Msty수동 — 직접 설치하면 omm이 그대로 링크합니다

• 여기서 수동은 마법사가 제조사의 설치 프로그램을 대신 실행해 주지 않는다는 뜻일 뿐입니다. 다운로드 링크를 출력해 주며, 앱이 존재하기만 하면 omm은 다른 러너와 마찬가지로 이를 감지하고 링크합니다.
• Jan은 PATH에 flatpak이 있어야 합니다. 없으면 마법사는 flatpak not found - install manually from https://jan.ai/download를 보고합니다.
• AnythingLLM의 유일한 공식 Linux 설치 방법은 AppArmor 프로필을 묻는 대화형 설치 프로그램이며 문서화된 silent 플래그가 없습니다. Msty는 Linux용 패키지가 아예 없습니다 — 이런 이유로 여기서는 둘 다 자동 설치되지 않습니다.
• KoboldCpp와 text-generation-webui는 x86_64 Linux 빌드만 제공하므로, ARM에서는 마법사가 대신 다운로드 페이지를 출력합니다.

07 / 08 · Linux

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

모델이 저장되는 위치

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

$ export OMM_HOME=/mnt/models/omm

• 이후 실행에서도 적용되도록 이 줄을 셸 프로필에 넣어 두세요.
• Ollama 자체의 모델 위치는 OLLAMA_MODELS를 따릅니다. LM Studio는 자체 home 포인터를 따르며, LM Studio가 omm이 찾을 수 없는 사용자 지정 디렉터리를 사용한다면 OMM_LMSTUDIO_MODELS_DIR을 설정하세요.

셸 자동 완성

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

$ omm --install-completion bash

제거

이 작업은 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 · Linux

문제가 생겼다면

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

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 이상 버전을 찾지 못했습니다. 설치 스크립트의 자동 설치는 apt-get이 있는 곳에서만 동작하며, 그런 곳에서도 apt가 실패하면 조용히 포기합니다.

   대처

   배포판의 패키지 매니저로 Python 3.10 이상을 설치하세요 — sudo apt install python3 python3-venv python3-pip, sudo dnf install python3, sudo pacman -S python — 그런 다음 설치 명령을 다시 실행하세요.

   출처

   install.sh:122-135

3. git not found. Install git first (needed to fetch omm from GitHub).

   원인

   omm은 검증된 Git 체크아웃으로부터 설치되는데, 여기서는 git이 없고 apt로도 설치할 수 없었습니다.

   대처

   사용 중인 패키지 매니저로 git을 설치한 뒤 설치 명령을 다시 실행하세요.

   출처

   install.sh:141-150

4. python3-venv not found (needed by pipx), installing it via apt...

   원인

   참고용 메시지입니다. Debian과 Ubuntu에서는 ensurepip가 별도 패키지로 제공되며, 없으면 pipx가 ensurepip is not available로 실패합니다.

   대처

   설치가 계속 진행된다면 별도로 할 일은 없습니다. apt를 사용하지 않는 배포판이라면 해당하는 패키지를 직접 설치하세요 — python3-virtualenv 또는 배포판의 python3 venv 패키지.

   출처

   install.sh:152-155

5. git 2.34+ is required to verify SSH commit signatures (found git version 2.30.0).

   원인

   git 버전이 너무 오래되어 SSH 커밋 서명을 확인할 수 없습니다. 설치 스크립트는 검증 불가 상태를 서명 오류와 동일하게 취급합니다.

   대처

   git을 업데이트한 뒤 설치 명령을 다시 실행하세요.

   출처

   install.sh:81

6. Signature verification failed - refusing to install untrusted code.

   원인

   스테이징된 커밋이 설치 스크립트의 신뢰 앵커에 있는 키로 서명되지 않았거나, 앞 항목과 마찬가지로 git이 서명을 아예 확인하지 못한 경우입니다.

   대처

   git을 업데이트한 뒤 다시 시도하세요. 그래도 실패한다면 일반 git clone으로 우회하지 말고, 대신 저장소에 이슈를 등록하세요.

   출처

   install.sh:396

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. bash: omm: command not found

    원인

    설치는 끝났지만 이 셸은 여전히 시작할 때의 PATH를 그대로 가지고 있습니다.

    대처

    새 셸을 여세요. 설치 스크립트도 마지막 줄에 같은 안내를 출력합니다.

    출처

    install.sh:508

11. Refusing non-absolute OMM_HOME: models/omm

    원인

    OMM_HOME은 절대 경로여야 합니다. 관련 메시지인 Refusing unsafe OMM_HOME이 나타나면 /나 홈 디렉터리 자체를 가리키고 있다는 뜻입니다.

    대처

    하위 디렉터리로 이어지는 전체 경로를 사용하세요. 예: export OMM_HOME=/mnt/models/omm.

    출처

    install.sh:11 and install.sh:14

12. flatpak not found - install manually from https://jan.ai/download

    원인

    이는 설치 스크립트가 아니라 설정 마법사 이야기입니다. Jan을 Linux에서 자동 설치할 수 있는 유일한 경로는 Flatpak입니다. omm은 다운로드 URL을 직접 추측하는 일이 없습니다.

    대처

    flatpak을 설치하고 Flathub remote를 추가한 뒤 omm setup을 다시 실행하세요 — 또는 출력된 링크에서 Jan을 직접 설치하세요. 어느 쪽이든 omm은 모델을 링크합니다.

    출처

    src/omm/linker.py:2116-2121

13. Refusing unrecognized custom OMM_HOME (missing .omm-managed): /mnt/models/omm

    원인

    설치 스크립트가 자신의 것으로 표시한 적 없는 사용자 지정 OMM_HOME으로 제거를 시도하고 있어, 제거 스크립트는 해당 폴더를 건드려도 안전한지 증명할 수 없습니다.

    대처

    OMM_HOME이 omm이 실제로 설치된 폴더를 가리키는지 확인한 뒤, 제거 스크립트를 다시 실행하세요.

    출처

    uninstall.sh:42

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