우분투에 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와 함께 즐거운 코딩 되세요!