우분투에 Gemini CLI 설치하는 방법: 완전 단계별 튜토리얼
필수 요구사항
Ubuntu에서 Gemini CLI 설치를 시작하기 전에 다음을 준비하세요:
- Ubuntu 버전: 20.04 LTS 이상 (22.04, 24.04, 26.04 완전 지원)
- 관리자 권한: 패키지 관리를 위한 sudo 권한
- 인터넷 연결: Node.js, npm 패키지 다운로드 및 인증에 필요
- Google 계정: Gemini 모델 접근을 위한 OAuth 로그인이 필요
- 권장 하드웨어: 인터랙티브 세션 중 원활한 성능을 위해 최소 4GB RAM 및 2 CPU 코어
기본 지식 가정: 터미널을 열고 기본 apt 및 bash 명령어를 실행할 수 있어야 합니다.
단계 1: 시스템 패키지 업데이트
패키지 목록을 새로고치고 기존 패키지를 업그레이드하여 종속성 충돌을 방지하세요:
sudo apt update && sudo apt upgrade -y
이 단계는 최신 보안 업데이트와 저장소 정보를 보장합니다.
단계 2: Node.js 20 이상 설치
Gemini CLI는 Node.js 버전 20 이상이 필요합니다. Ubuntu의 기본 저장소는 종종 이전 버전을 포함합니다 (예: Ubuntu 24.04의 Node 18).
권장 방법: NodeSource 저장소
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
대안: nvm(Node Version Manager) 사용
더 쉬운 버전 관리를 위해:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use BOBO
nvm alias default 20
설치 확인:
node --version
npm --version
Node.js에는 v20.x.x와 같은 출력이, npm에는 일치하는 버전이 표시되어야 합니다.
단계 3: Gemini CLI 설치
전역 설치 (일상 사용에 권장)
npm install -g @google/gemini-cli
이렇게 하면 gemini 명령어가 시스템 전체에서 사용 가능해집니다.
영구 설치 없이 빠른 테스트
먼저 사용해보고 싶다면:
npx @google/gemini-cli
사용자 수준 설치 (권한 문제 방지)
전역 설치에 권한 오류가 발생하면:
mkdir -p ~/.local/bin
npm config set prefix '~/.local'
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
단계 4: 설치 확인
Gemini CLI가 올바르게 설치되었는지 확인하세요:
gemini --version
예상 출력은 Gemini CLI의 현재 버전을 보여줍니다.
단계 5: 실행 및 인증
CLI를 처음 실행하세요:
gemini
도구는 Google 로그인을 요청합니다. 브라우저 창이 자동으로 열립니다. OAuth 흐름을 완료하고 터미널로 돌아오세요.
성공적인 인증 후 인터랙티브 Gemini CLI 인터페이스가 로드됩니다. 사용 가능한 명령어를 보려면 /help를 사용하세요.
최적의 방법: 실행하기 전에 프로젝트 디렉토리로 이동하세요:
cd ~/my-project
gemini
일반적인 문제와 해결 방법
-d 'gemini: command not found': 터미널을 재시작하거나 source ~/.bashrc를 실행하세요. echo $PATH로 PATH를 확인하세요.
-
npm install 중 권한 거부됨: 위의 사용자 수준 설치 방법을 사용하고
sudo npm을 피하세요. -
Node.js 버전 오류: NodeSource 설정을 다시 실행하거나 nvm으로 버전을 변경하세요.
node --version으로 확인하세요. -
인증 실패: 브라우저 팝업 차단기를 비활성화하고 쿠키가 활성화되어 있는지 확인한 후 다시 시도하세요. 필요한 경우 npm 캐시를 지우세요:
npm cache clean --force. -
네트워크 타임아웃 또는 다운로드 오류 (예: ripgrep 사전 빌드): 안정적인 인터넷 연결을 확인하세요. 설치를 재시도하거나 우회책으로
npx를 사용하세요. -
빌드 도구 누락: 개발 의존성을 설치하세요:
sudo apt install -y build-essential python3
- WSL 특정 문제: 컴파일 오류가 발생하면 WSL이 아닌 표준 Ubuntu 터미널에서 명령을 실행하세요.
더 많은 도움이 필요하면 공식 GitHub 저장소를 참조하세요: https://github.com/google-gemini/gemini-cli.
다음 단계
- 핵심 명령어 탐색: CLI 내에서
/help,/model, 또는/settings를 입력하세요. - 프로젝트에서 사용: Gemini에게 코드 설명, 함수 리팩터링, 자연어 프롬프트로 새 파일 생성 등을 요청하세요.
- 사용자 지정: 테마, 기본 모델, 확장 기능을 위해
~/.config/gemini-cli/의 구성 파일을 편집하세요. - 정기적으로 업데이트:
npm update -g @google/gemini-cli를 실행하여 최신 개선 사항을 받으세요. - 도구 통합: Git 통합과 같은 고급 에이전트 작업을 위해 내장 확장 기능 및 MCP 서버로 실험해 보세요.
이제 Ubuntu 터미널에서 바로 강력한 AI 코딩 어시스턴트로 Gemini CLI를 사용할 준비가 되었습니다. 프로젝트 폴더에서 간단한 프롬프트로 시작하고 점차 더 복잡한 에이전트 작업을 구축하세요.
Gemini와 함께 즐거운 코딩 되세요!