Gemini CLI 설치 가이드 (Homebrew 이용)

사실 한국어도 한다. ^^;;

Intro.

이 문서는 Windows(WSL Ubuntu)와 macOS(Zsh) 환경에서

패키지 매니저인 Homebrew를 사용하여 Gemini CLI를 설치하는 방법을 안내함.

2024.09.08 - [utils] - [Summary] Package Manager

[Summary] Package Manager

---

Gemini CLI란?

Gemini CLI는 구글의 Gemini를 터미널(Terminal) 환경에 통합한 Commnad-Line Interface Tool임.

 

더 자세히 말한다면,

Gemini CLI는 shell 환경에서 명령 실행 보조, 코드 작업, 파일 확인, 프로젝트 context 기반 응답 등을 지원하는 AI agent 성격의 도구이며 현 수준에선 가장 저렴하게 사용가능한 쓸만한 AI Agent임.

 

관련한 문서 자료(공식 사이트)는 다음 URL을 확인할 것:

https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#gemini-cli

GitHub - google-gemini/gemini-cli: An open-source AI agent that brings the power of Gemini directly into your terminal.

---

 

WSL (Windows Subsystem for Linux)을 사용한 이유.

• Windows 의 일반적인 터미널인 cmd(command prompt)와 powershell 에서 Gemini CLI를 사용하는 것보다
  WSL이 Gemini CLI와 보다 궁합이 잘 맞음.
  • 2025.12.26 현재 Gemini CLI 의 /copy 명령어가 cmd와 powershell 모두 동작하지 않는 등의 문제가 있으나
    WSL에서는 문제가 없었음.
  • Ubuntu를 많이 쓰기 때문에 Ubuntu로 기술했으나, Debian의 경우도 큰 차이는 없음.

https://dsaint31.tistory.com/423

[CE] Introduction of WSL

---

 

Homebrew를 사용한 이유.

• 사실 "npm (Node Package Manager)을 사용하여 Gemini CLI를 설치"하는 것이 보다 일반적임
  ("0. 정식설치 안내" 참고).
• 개인적으로 npm을 별로 사용하지 않고, macOS나 Linux에서 똑같은 방법으로 설치하길 원해서 Homebrew를 선택함.

2024.09.08 - [utils] - [Utils] homebrew - Summary

[Utils] homebrew - Summary

---

0. 정식 설치 안내

정식 설치는 주로 npm을 사용하며,
node.js나 npm은 NVM을 통해 설치하는게 좋음:
NVM 설치를 위해선 다음을 참고할 것:

2026.03.25 - [개발환경] - NVM (Node Version Manager)

NVM (Node Version Manager)

 

정식 설치법은 아래의 URL 을 참고하는게 정석임:

https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install

GitHub - google-gemini/gemini-cli: An open-source AI agent that brings the power of Gemini directly into your terminal.

 

nvm을 설치하고 나서 Windows 에 직접 Gemini CLI를 설치하는 방법은 다음을 참고:

https://blog.naver.com/dsaint31/224242974782

Install Gemini CLI for Windows

---

1. macOS 설치 (Zsh 환경)

macOS는 Gemini CLI를 Homebrew로 설치하기가 매우 쉬움
(사실 Homebrew는 macOS에서 가장 널리 사용되는 패키지 매니저임).

 

Homebrew 설치 시 필요한 개발 도구(Xcode Command Line Tools)가 자동으로 구성됨.

---

1단계: Homebrew 설치

• Terminal (or iterm2)에서 공식 설치 스크립트를 실행하여 Homebrew를 설치함.
• 이 과정에서 관리자 권한(비밀번호)을 요구할 수 있으며, Xcode Command Line Tools가 없다면 자동 설치 팝업이 뜸.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2023.09.29 - [utils] - [Util] curl 간단사용법 정리 : web의 자원 다운로드하기.

[Util] curl 간단사용법 정리 : web의 자원 다운로드하기.

---

다음 내용을 보고 따라서 설치하는 것을 권함:
https://ds31x.tistory.com/336#%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0

[Utils] homebrew - Summary

---

2단계: 경로(Path) 설정 (필수)

• 설치가 끝났다고 바로 brew 명령어가 되지 않음.
• macOS 시스템이 brew 명령어의 위치를 알 수 있도록 path(경로)를 등록해야 함.
• 설치 완료 로그 맨 하단 "Next steps:" 에 나오는 명령어 2~3줄을 복사해서 실행하는 것이 가장 정확함.

(Apple Silicon 모델 예시)

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

• 이건 예시일 뿐, 가급적 설치 완료  로그 에서 지시하는대로 해야함.
• Intel Mac의 경우 경로가 조금 다르므로 꼭 설치완료 로그의 지시사항을 따르는 것을 권장함.

---

3단계: Gemini CLI 저장소 연결 및 설치 (Tap 연결 필수 아님.)

현재 Gemini CLI는 Homebrew 공식 formula로 설치가 가능하므로 tap 연결이 필요 없음.

• Tap 연결 (brew tap):
  • Gemini CLI는 Homebrew의 기본 목록(Core)에 없으므로,
  • 구글이 관리하는 전용 저장소(google-gemini/gemini-cli)를 내 컴퓨터에 연결해줘야 함.
• 설치 (brew install):
  • 연결된 저장소에서 Gemini CLI 패키지를 다운로드하고 설치함.

# brew tap google-gemini/gemini-cli #시도할 경우 인증이 필요하니 tap연결하지 말 것.
brew install gemini-cli

tap의 개념은 다음을 참고:

2023.12.15 - [Mac] - [Homebrew] Formula 와 cask 의 차이 + tap

[Homebrew] Formula 와 cask 의 차이 + tap

---

4단계: 설치 결과 확인

• 설치된 Gemini CLI의 버전을 출력하여 정상적으로 실행되는지 검증함.

gemini --version

---

2. Windows 설치 (WSL: Ubuntu 환경)

Windows에서는 리눅스 가상 환경인 WSL(Windows Subsystem for Linux)을 통해 설치를 진행함.

리눅스 환경은 macOS와 달리 기본 개발 도구가 없으므로 추가적인 라이브러리 설치가 필요함.

---

1단계: Zsh 설치 및 기본 셸 설정

• Ubuntu의 기본 셸인 Bash 대신, 더 강력한 기능을 제공하는 Zsh를 설치하고 기본값으로 변경함.

  sudo apt update && sudo apt install -y zsh
  chsh -s $(which zsh)
  zsh
  # (설정 마법사가 나오면 숫자 '2'를 눌러 추천 설정을 적용)

서버 시스템에선 bash가 보다 권장되나... Gemini CLI를 서버에 설치하진 않을 것으므로 개인용에 적합한 zsh을 사용한다.

추가로 oh my zsh도 설치해주면 좋다.

---

2단계: 필수 의존성 라이브러리 설치 (build-essential)

• 왜 필요한가?:
  • Homebrew는 프로그램 설치 시 소스 코드를 직접 컴파일(Build)해야 하는 경우가 빈번함.
  • Formula는 소스를 빌드하여 시스템에서 사용 가능하게 만드는 명세서이므로 실제 빌드 과정을 요구함.
  • 미리 빌드된 바이너리인 Bottle이 제공되기도 하지만, 모든 패키지나 환경에서 이를 보장할 수 없으므로 로컬 빌드 환경 구축이 필수적임.
• 역할:
  • gcc(C언어 컴파일러), make(빌드 도구) 등 리눅스에서 소프트웨어를 설치하고 실행하는 데 필수적인 도구 모음을 설치함.
  • 이 과정이 없으면 brew install 도중 에러가 발생할 확률이 매우 높음.

sudo apt-get install build-essential curl procps file git

• 사실 build-essential과 curl만으로 충분하다. 

---

3단계: Linux용 Homebrew 설치

• 리눅스 환경에 최적화된 Homebrew 설치 스크립트를 실행함.
• 아래 스크립트는 curl을 사용함. 없다면 설치를 미리 해야 함: sudo apt-get install curl

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

 

다음 url을 읽어보면서 설치해도 됨 (3단계와 4단계를 커버함):

2023.09.05 - [Linux] - [Linux] homebrew 설치하기 (Ubuntu)

[Linux] homebrew 설치하기 (Ubuntu)

---

4단계: Linux용 경로 설정 (필수)

• 리눅스용 Homebrew는 /home/linuxbrew/.linuxbrew라는 특수 경로에 설치됨.
• 이 경로를 Zsh 설정 파일(.zshrc)에 등록해야만 brew 명령어를 어디서든 사용할 수 있음.

(echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.zshrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

 

• Linux용 Homebrew는 기본적으로 /home/linuxbrew/.linuxbrew라는 비표준 경로에 설치됨.
• 리눅스 시스템은 이 경로에 명령어들이 있다는 것을 모르기 때문에, "여기에도 실행 파일이 있으니 찾아봐라" 라고 알려주는 설정이 필요함.
• 첫번째 줄
  • ( ... ): 괄호 안의 명령어들을 하나의 그룹으로 묶어서 실행함.
  • echo: 빈 줄을 하나 출력함. (설정 파일의 기존 내용과 섞이지 않게 줄바꿈을 하기 위함)
  • echo 'eval ...': 홑따옴표 안의 문자열 내용을 그대로 출력함.
  • eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)":
    • $(...)은 가로안의 명령어를 실행한 결과 문자열로 치환됨
    • eval "..."은 쌍따옴표의 명령어를 실행.
  •  >> ~/.zshrc: 앞에서 출력된 내용을 Zsh 설정 파일(.zshrc)의 맨 끝에 추가(Append)함.
  • 결과: 이제 터미널을 새로 열 때마다 이 설정이 자동으로 실행되어 brew를 쓸 수 있게 됨.
•  두 번째 줄: 즉시 적용
  • $( ... ): 괄호 안의 명령어를 실행하고, 그 결과값으로 대체됨.
  • /home/linuxbrew/.linuxbrew/bin/brew shellenv 를 실행하면, PATH, MANPATH 등 필요한 환경 변수 설정 스크립트가 출력됨.
  • eval: 위에서 출력된 스크립트 코드를 현재 터미널에서 즉시 실행함.
  • 결과: 터미널을 껐다 켜지 않아도 방금 설치한 brew 명령어를 바로 사용할 수 있게 됨.
• 요약
  • 첫 번째 줄: "다음번에 터미널을 켤 때부터 brew를 쓰게 해줘." (영구 설정)
  • 두 번째 줄: "지금 당장 brew를 쓰게 해줘." (즉시 적용)

사실, 설치 완료 로그에 해당 내용에 대한 안내가 나온다.
이 문서의 내용보다 해당 로그의 내용대로 해야 정확하다.
이 문서는 해당 로그의 내용을 반영하여 작성했으나 추후에 변경이 이루어질수도 있으므로 반드시 설치로그를 확인할 것.

---

5단계: Gemini CLI 저장소 연결 및 설치 (Tap 필수 아님)

• macOS와 동일하게 전용 저장소(tap)를 연결한 후 패키지 설치를 진행함.

  # brew tap google-gemini/gemini-cli # 실행시 인증요구하고 에러로 이어짐. 주석처리
  
  # 현재 core formula이므로 tap 추가 없이 설치가능함.
  brew install gemini-cli

---

6단계: 설치 결과 확인

버전 정보를 확인하여 설치가 성공적으로 완료되었는지 테스트함. 

gemini --version

 

이후 다음의 문서를 통해 사용법을 익혀보길 권함:

2026.04.13 - [개발환경] - [Summary] Gemini CLI 사용법 기초

[Summary] Gemini CLI 사용법 기초

---

같이 보면 좋은 자료들

2023.12.15 - [Mac] - [Homebrew] 사용법 요약본

[Homebrew] 사용법 요약본

2025.12.26 - [CE] - Gemini CLI와 함께하는 터미널(CLI) 명령어 학습하기

Gemini CLI와 함께하는 터미널(CLI) 명령어 학습하기

---