# 우분투에 Gemini CLI 설치하는 방법: 완전 단계별 튜토리얼

우분투에 Google Gemini CLI를 설치하는 단계별 튜토리얼입니다. Node.js 20+ 설정, npm 전역 설치, 인증, 검증 및 우분투 LTS에서의 일반적인 문제 해결을 다룹니다.

Canonical URL: https://a2a-mcp.org/blog/how-to-install-gemini-cli-on-ubuntu-ko

Language: ko

Published: 2026-04-07

Updated: 2026-04-07

## 필수 요구사항

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: 시스템 패키지 업데이트

패키지 목록을 새로고치고 기존 패키지를 업그레이드하여 종속성 충돌을 방지하세요:

```bash
sudo apt update && sudo apt upgrade -y
```

이 단계는 최신 보안 업데이트와 저장소 정보를 보장합니다.

## 단계 2: Node.js 20 이상 설치

Gemini CLI는 **Node.js 버전 20 이상**이 필요합니다. Ubuntu의 기본 저장소는 종종 이전 버전을 포함합니다 (예: Ubuntu 24.04의 Node 18).

### 권장 방법: NodeSource 저장소

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
```

### 대안: nvm(Node Version Manager) 사용

더 쉬운 버전 관리를 위해:

```bash
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
```

설치 확인:

```bash
node --version
npm --version
```

Node.js에는 `v20.x.x`와 같은 출력이, npm에는 일치하는 버전이 표시되어야 합니다.

## 단계 3: Gemini CLI 설치

### 전역 설치 (일상 사용에 권장)

```bash
npm install -g @google/gemini-cli
```

이렇게 하면 `gemini` 명령어가 시스템 전체에서 사용 가능해집니다.

### 영구 설치 없이 빠른 테스트

먼저 사용해보고 싶다면:

```bash
npx @google/gemini-cli
```

### 사용자 수준 설치 (권한 문제 방지)

전역 설치에 권한 오류가 발생하면:

```bash
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가 올바르게 설치되었는지 확인하세요:

```bash
gemini --version
```

예상 출력은 Gemini CLI의 현재 버전을 보여줍니다.

## 단계 5: 실행 및 인증

CLI를 처음 실행하세요:

```bash
gemini
```

도구는 Google 로그인을 요청합니다. 브라우저 창이 자동으로 열립니다. OAuth 흐름을 완료하고 터미널로 돌아오세요.

성공적인 인증 후 인터랙티브 Gemini CLI 인터페이스가 로드됩니다. 사용 가능한 명령어를 보려면 `/help`를 사용하세요.

**최적의 방법**: 실행하기 전에 프로젝트 디렉토리로 이동하세요:

```bash
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`를 사용하세요.

- **빌드 도구 누락**: 개발 의존성을 설치하세요:

```bash
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와 함께 즐거운 코딩 되세요!