개발 환경 설치 가이드

Antigravity를 최대한 활용하기 위한 Python, Node.js, Git, uv 설치 방법을 안내합니다.

개발 환경 설치 가이드 #

Antigravity 자체는 독립 실행 앱이지만, AI가 생성한 코드를 실행하려면 프로그래밍 언어와 도구가 필요합니다. 아래 도구들을 미리 설치해 두면 Antigravity의 능력을 최대로 활용할 수 있습니다.

왜 이런 도구들이 필요한가?

필수 및 권장 설치 목록

필수 및 권장 설치 도구 목록
도구	필요성	역할	설치하지 않으면
uv 권장	권장 (Python 자동 관리)	Python 설치·버전 관리·패키지 관리·가상환경 자동화	Python을 직접 설치·관리해야 하며 패키지 설치 속도 저하
Node.js 18+	권장	웹 개발, MCP 서버 연동, 패키지 관리	React/Next.js 프로젝트 생성 불가, MCP 서버 연결 불가
Git	권장	버전 관리, GitHub 연동, 코드 이력 추적	프로젝트 히스토리 관리 불가, GitHub 작업 제한
Python 3.10+	선택 (uv 사용 시 자동 설치)	데이터 분석, 스크립트 실행, 자동화	uv가 자동 관리하므로 직접 설치 불필요. uv 미사용 시에만 필요
pip / npm	자동 포함	Python/Node.js 패키지 설치	Python/Node.js 설치 시 함께 포함됨

비유로 이해하기

Antigravity는 건축 설계사와 같습니다. 설계사가 도면을 그리지만, 실제 건물을 짓는 것은 현장의 도구(망치, 드릴, 크레인)입니다. Python, Node.js, Git은 바로 그 현장 도구에 해당합니다.

uv — 차세대 Python 패키지 관리자 #

uv는 Rust로 작성된 초고속 Python 패키지 관리자입니다. 기존 pip보다 10~100배 빠르고, Python 버전 관리까지 한 번에 해결합니다.

왜 uv를 써야 하나?

pip과 uv 패키지 관리자 비교
비교 항목	pip (기존)	uv (추천)
패키지 설치 속도	보통	10~100배 빠름 (Rust 기반 병렬 처리)
의존성 해결	느리고 가끔 충돌	빠르고 정확한 SAT 솔버
Python 버전 관리	별도 도구 필요 (pyenv 등)	`uv python install 3.12` 한 줄로 해결
가상환경 관리	`python -m venv` + 활성화 필요	`uv venv` 자동 생성, `uv run`으로 자동 활성화
프로젝트 관리	requirements.txt 수동 관리	`pyproject.toml` 기반 자동 관리
도구 실행	`pip install` 후 실행	`uvx ruff check .` — 설치 없이 바로 실행 (npx와 유사)

비유로 이해하기

pip이 일반 택배라면, uv는 로켓배송입니다. 같은 패키지를 설치하는데 체감 속도가 완전히 다릅니다. 특히 프로젝트를 새로 시작하거나 의존성이 많은 프로젝트에서 차이가 극명합니다.

uv 설치

운영체제별 uv 설치 명령어
운영체제	설치 명령어	비고
macOS / Linux	`curl -LsSf https://astral.sh/uv/install.sh \| sh`	공식 설치 스크립트. 홈 디렉토리에 설치됨
macOS (Homebrew)	`brew install uv`	Homebrew 사용자라면 이 방법이 간편
Windows	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`	PowerShell에서 실행. 실행 정책·네트워크·PATH 오류 발생 시 아래 Windows PowerShell 트러블슈팅 참고
Windows (winget)	`winget install astral-sh.uv`	winget 사용자라면 이 방법이 간편
pip으로 설치	`pip install uv`	가능하지만 standalone 설치를 권장. pip 버전은 업데이트가 느릴 수 있음

      설치 확인
      # uv 버전 확인
uv --version
# 출력 예: uv 0.7.x (설치 시점에 따라 다름)
    

⚠️ Windows PowerShell 트러블슈팅 #

Windows PowerShell에서 uv를 설치할 때 자주 발생하는 6가지 시나리오와 해결 방법입니다. 각 사례별로 증상·원인·해결 명령을 함께 정리했습니다.

📌 빠른 진단 — 어느 시나리오에 해당하는가?

설치 명령 실행 시 빨간 글씨로 PSSecurityException·UnauthorizedAccess 표시 → 시나리오 1
'irm'은 cmdlet, 함수, 스크립트 파일 또는 ... 인식되지 않습니다 → 시나리오 2
설치는 끝났는데 새 창에서 uv: command not found 또는 'uv'은(는) 인식되지 않는 → 시나리오 3
회사·학교 PC에서 이 시스템에서 스크립트 실행이 비활성화 → 시나리오 4
The remote server returned an error·SSL 오류 → 시나리오 5
위 어떤 방법도 안 통할 때 → 시나리오 6 (winget 대안)

시나리오 1 — ExecutionPolicy 차단 (PSSecurityException)

증상:

      PowerShell 오류 예시
      install.ps1 : 이 시스템에서 스크립트를 실행할 수 없으므로 ... 파일을 로드할 수 없습니다.
+ CategoryInfo          : 보안 오류: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
    

원인: Windows의 기본 실행 정책(Restricted)이 PowerShell 스크립트(.ps1) 실행을 차단합니다.

해결 — 권장(영구): 현재 사용자에 한해 RemoteSigned로 변경합니다 (관리자 권한 필요).

      PowerShell (관리자)
      # 시작 메뉴 → PowerShell 우클릭 → "관리자 권한으로 실행"
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 확인 메시지가 나오면 Y 입력 후 Enter

# 이후 일반 PowerShell에서 uv 설치 명령 재실행
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
    

해결 — 일회성: 설치 명령 자체에 ByPass 플래그를 사용합니다 (공식 안내 명령). 보안 정책은 변경하지 않음.

      PowerShell
      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    

시나리오 2 — `irm`·`iex` 명령 미인식 (PowerShell 5.x 이하)

증상: 'irm'은(는) cmdlet, 함수, 스크립트 파일 또는 실행 가능한 프로그램의 이름으로 인식되지 않습니다.

원인: Windows 7/8 또는 일부 구형 Windows 10 환경에서 PowerShell 2.0이 기본일 수 있습니다. irm(Invoke-RestMethod)·iex(Invoke-Expression)는 PowerShell 3.0+ 명령입니다.

해결: PowerShell 버전 확인 후 PowerShell 7로 업데이트 (또는 명시적 cmdlet 사용).

      PowerShell
      # 현재 PowerShell 버전 확인
$PSVersionTable.PSVersion

# PowerShell 7 설치 (winget 사용 시 가장 간편)
winget install --id Microsoft.Powershell --source winget

# 또는 풀 명령으로 우회 (구버전에서도 동작)
powershell -ExecutionPolicy ByPass -c "Invoke-Expression (Invoke-RestMethod -Uri https://astral.sh/uv/install.ps1)"
    

시나리오 3 — 설치 후 `uv` 명령 인식 안 됨 (PATH 미반영)

증상: 설치 완료 메시지가 나왔는데 새로 연 PowerShell·명령 프롬프트에서 'uv'은(는) 인식되지 않는 오류.

원인: uv는 %USERPROFILE%\.local\bin에 설치되며, 이 경로가 시스템 PATH에 없으면 셸이 uv를 찾지 못합니다.

해결:

      PowerShell
      # 1. 설치 위치 확인 (보통 .local\bin 또는 .cargo\bin)
Test-Path "$env:USERPROFILE\.local\bin\uv.exe"
Test-Path "$env:USERPROFILE\.cargo\bin\uv.exe"

# 2. 현재 사용자 PATH에 영구 추가 (관리자 권한 불필요)
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.local\bin",
  "User"
)

# 3. PowerShell을 완전히 닫고 새로 열기 → uv --version 재시도
    

대안: PowerShell을 닫고 새로 열면 자동 적용되는 경우가 많습니다. 그래도 안 되면 위 명령으로 명시적 추가.

시나리오 4 — 회사·학교 PC에서 ExecutionPolicy 변경 차단

증상: Set-ExecutionPolicy 실행 시 이 그룹 정책에 의해 ... 변경할 수 없습니다 또는 액세스가 거부되었습니다.

원인: 조직 그룹 정책(GPO)으로 PowerShell 실행 정책이 잠겨 있습니다. 사용자가 변경할 수 없음.

해결: 정책을 우회하지 말고, 정책에 영향받지 않는 대안을 사용합니다.

(권장) winget 사용: Microsoft Store 패키지로 설치 — PowerShell 정책 무관 (시나리오 6 참고)
스크립트 다운로드 후 직접 실행: install.ps1을 IT 부서 승인 후 직접 다운로드해 인라인 실행
pip 사용: Python이 이미 있다면 pip install uv (단, standalone 버전보다 업데이트 느림)
IT 부서에 요청: 개발 도구 설치 정책 예외 신청

시나리오 5 — 네트워크·SSL 오류 (방화벽·프록시)

증상: The remote server returned an error: (407) Proxy Authentication Required 또는 The underlying connection was closed: An unexpected error occurred on a send.

원인: 회사·기관 방화벽이 astral.sh로의 직접 접근을 차단하거나 프록시 인증이 필요합니다.

해결:

      PowerShell
      # 1. 프록시가 필요한 환경이라면 환경변수 설정
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"

# 2. TLS 1.2 강제 (구버전 .NET에서 SSL 오류 시)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# 3. 위 설정 후 설치 재시도
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    

대안: 위 방법도 안 되면 winget이나 pip 사용(시나리오 6) — 두 방법은 별도 채널 사용으로 방화벽 우회 가능성 높음.

시나리오 6 — 모두 안 통할 때: winget 대안 (가장 안정적)

권장 시점: 위 1-5 시나리오 중 어느 것도 해결 안 될 때, 또는 처음부터 가장 안정적인 방법을 원할 때.

장점: Microsoft 공식 패키지 매니저이므로 회사 PC에서도 거의 항상 동작. PowerShell 실행 정책 무관. PATH 자동 등록.

      PowerShell 또는 명령 프롬프트
      # winget 사용 가능 여부 확인 (Windows 10 1809+ / Windows 11 기본 포함)
winget --version

# uv 설치
winget install astral-sh.uv

# 설치 확인 (새 터미널 열고 실행)
uv --version
    

winget이 없다면: Microsoft Store에서 "App Installer"를 설치하면 winget이 함께 설치됩니다.

📚 추가 참고 자료:

about_Execution_Policies (Microsoft Learn 한국어) — 실행 정책 전체 설명
uv 공식 설치 문서 — 모든 설치 방법 비교
winget 공식 문서 — Windows 패키지 매니저

uv 핵심 사용법

      Python 버전 관리 (pyenv 대체)
      # 사용 가능한 Python 버전 목록
uv python list

# Python 3.12 설치
uv python install 3.12

# 특정 버전의 Python 사용
uv python install 3.11 3.12 3.13
# 여러 버전을 동시에 설치할 수 있습니다
    

      프로젝트 생성 및 패키지 관리
      # 새 프로젝트 시작 (pyproject.toml 자동 생성)
uv init my-project
cd my-project

# 패키지 추가 (pip install 대체)
uv add pandas numpy matplotlib
# → 가상환경 자동 생성 + 패키지 설치 + pyproject.toml 업데이트

# 개발용 패키지 추가
uv add --dev pytest ruff

# 스크립트 실행 (가상환경 활성화 불필요)
uv run python main.py
uv run pytest
    

      도구 실행 — uvx (npx의 Python 버전)
      # 설치 없이 도구 바로 실행
uvx ruff check .          # 코드 린팅
uvx black .               # 코드 포매팅
uvx jupyter lab           # Jupyter Lab 실행
uvx cookiecutter gh:...   # 프로젝트 템플릿 생성
    

      기존 pip 명령어와 비교
      # pip 방식 (기존)
python -m venv .venv            # 가상환경 생성
source .venv/bin/activate       # 가상환경 활성화
pip install pandas numpy        # 패키지 설치
pip freeze > requirements.txt   # 의존성 저장
python main.py                  # 실행

# uv 방식 (추천) — 위의 모든 과정이 간소화
uv add pandas numpy             # 가상환경 + 설치 + 의존성 관리 한 번에
uv run python main.py           # 가상환경 자동 활성화 + 실행
    

Antigravity에서 uv 활용: Antigravity가 Python 프로젝트를 생성할 때 uv가 설치되어 있으면 pip 대신 uv를 사용하여 훨씬 빠르게 패키지를 설치합니다. 특히 데이터 분석 라이브러리(pandas, numpy, scikit-learn 등)처럼 의존성이 많은 패키지에서 설치 시간 차이가 큽니다.

자주 발생하는 uv 오류와 해결

uv 설치 및 사용 중 자주 발생하는 오류와 해결 방법
오류 메시지	원인	해결 방법
`uv: command not found`	설치 후 PATH 미등록 또는 터미널 미재시작	터미널을 완전히 닫고 새로 열기. 안 되면 `source ~/.zshrc` (macOS/Linux)
`No solution found when resolving dependencies`	패키지 간 버전 충돌	`uv add 패키지명==특정버전`으로 버전 고정, 또는 `uv add --resolution lowest-direct 패키지명`
`error: Python 3.x is not installed`	지정한 Python 버전 미설치	`uv python install 3.x`로 먼저 Python 설치 후 재시도
가상환경이 생성되지 않음	프로젝트 루트에 `pyproject.toml`이 없음	`uv init`으로 프로젝트 초기화 후 `uv add` 실행

Node.js 설치 #

웹 프론트엔드/백엔드 개발과 MCP 서버 연동에 필수입니다. GitHub, Notion 등 외부 서비스 연결 시 npx 명령이 필요합니다.

방법 A: 공식 사이트에서 다운로드 (초보자 추천)

Node.js 공식 사이트 다운로드 설치 단계
단계	내용	상세 설명
1	공식 사이트 접속	nodejs.org에 접속합니다
2	LTS 버전 다운로드	메인 페이지에 두 버전이 표시됩니다. 왼쪽의 LTS (Long Term Support) 버전을 클릭하세요. 안정적이고 호환성이 좋습니다.
3	설치 프로그램 실행	macOS: `.pkg` 파일 더블클릭 → "계속" 반복 → "설치" Windows: `.msi` 파일 더블클릭 → 기본 옵션 그대로 "Next" 반복
4	설치 확인	터미널(macOS) 또는 명령 프롬프트(Windows)를 새로 열고 `node --version` 입력

LTS vs Current 차이: LTS(장기 지원)는 30개월간 보안 업데이트를 받는 안정 버전입니다. Current는 최신 기능이 포함되지만 변경이 잦습니다. 특별한 이유가 없다면 항상 LTS를 선택하세요.

방법 B: Homebrew / 패키지 관리자로 설치

운영체제별 Node.js 설치 명령어
운영체제	명령어	비고
macOS	`brew install node`	npm, npx 자동 포함
Windows	`winget install OpenJS.NodeJS.LTS`	PowerShell(관리자)에서 실행
Linux (Ubuntu/Debian)	`sudo apt update && sudo apt install nodejs npm`	버전이 낮을 수 있음. 최신 버전은 NodeSource 저장소 추가 권장

방법 C: nvm으로 설치 (여러 버전 관리)

프로젝트마다 다른 Node.js 버전이 필요할 때 유용합니다.

      터미널 (macOS / Linux)
      # nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.3/install.sh | bash
# (최신 버전은 github.com/nvm-sh/nvm 에서 확인하세요)

# 터미널 재시작 후
nvm install --lts
nvm use --lts

# 설치 확인
node --version
    

      설치 확인 (모든 OS 공통)
      # Node.js 버전 확인 (18 이상 권장)
node --version
# 출력 예: v22.x.x (설치 시점에 따라 다름)

# npm (패키지 관리자) 확인
npm --version
# 출력 예: 10.x.x

# npx (패키지 실행 도구) 확인 — MCP 서버 연동에 필수
npx --version
# 출력 예: 10.x.x
    

Node.js가 특히 필요한 경우: MCP 서버 연결 (GitHub, Notion 등), React/Next.js/Vue 프로젝트, TypeScript 개발, 웹앱 빌드 및 번들링

Git 설치 #

코드 버전 관리와 GitHub 연동에 사용됩니다. 프로젝트의 변경 이력을 추적하고, 실수 시 이전 상태로 되돌릴 수 있습니다.

macOS에서 Git 설치

macOS에서는 3가지 방법으로 Git을 설치할 수 있습니다.

macOS에서 Git 설치 방법 비교
방법	명령어 / 절차	설명
Xcode CLI 도구 (추천)	`xcode-select --install`	터미널에 입력하면 팝업이 뜸 → "설치" 클릭. Git 외에 컴파일러 등 개발 도구가 함께 설치됩니다. macOS 개발 시 어차피 필요한 도구입니다.
Homebrew	`brew install git`	Xcode CLI보다 최신 버전의 Git을 사용할 수 있습니다
공식 사이트	git-scm.com/downloads/mac	설치 프로그램(.dmg)을 다운로드해서 설치. 보안 경고가 뜨면 시스템 설정 → 개인정보 보호 및 보안 → "확인 없이 열기" 클릭

Windows에서 Git 설치

Windows에서 Git 설치 단계
단계	내용	상세 설명
1	공식 사이트 접속	git-scm.com → "Download for Windows" 클릭
2	설치 프로그램 실행	다운로드된 `.exe` 파일 실행
3	설치 옵션	대부분 기본값 그대로 "Next". "Adjusting your PATH" 단계에서 "Git from the command line and also from 3rd-party software" 선택 (기본값)
4	설치 완료	Git Bash, Git GUI가 함께 설치됩니다. 명령 프롬프트, PowerShell에서도 `git` 명령 사용 가능

Linux에서 Git 설치

      터미널 (Linux)
      # Ubuntu / Debian
sudo apt update && sudo apt install git

# Fedora / RHEL
sudo dnf install git

# 대부분의 배포판에서 이미 설치되어 있습니다
    

      설치 확인 및 초기 설정 (모든 OS 공통)
      # Git 버전 확인
git --version
# 출력 예: git version 2.43.0

# 최초 사용 시 사용자 정보 설정 (한 번만 하면 됩니다)
git config --global user.name "홍길동"
git config --global user.email "hong@example.com"

# 설정 확인
git config --global --list
# 출력 예:
# user.name=홍길동
# user.email=hong@example.com
    

Git이 특히 필요한 경우: AI가 코드를 대량 수정할 때 변경 이력 추적, GitHub에 코드 공유/백업, GitHub MCP 연동, 팀 협업

Git SSH 키 발급 및 설정 선택

GitHub에 코드를 push할 때 매번 비밀번호를 입력하지 않으려면 SSH 키를 설정합니다. HTTPS + Personal Access Token(PAT) 방식으로도 push가 가능하므로, 이 절은 필수 단계가 아닌 선택 단계입니다. SSH 키는 공개키/개인키 쌍으로 구성되며, 공개키를 GitHub에 등록하면 별도 입력 없이 안전하게 인증됩니다.

SSH vs HTTPS: HTTPS는 토큰 기반 인증이 필요하고 만료 관리가 번거롭습니다. SSH 키는 한 번 설정하면 반영구적으로 사용할 수 있어 대부분의 개발자가 SSH 방식을 권장합니다.

1단계: 기존 SSH 키 확인

먼저 이미 SSH 키가 있는지 확인합니다.

      터미널 (모든 OS 공통)
      # 기존 SSH 키 확인
ls -al ~/.ssh

# id_ed25519.pub 또는 id_rsa.pub 파일이 있으면 이미 키가 존재합니다
# 파일이 없거나 .ssh 디렉토리가 없으면 2단계로 진행하세요
    

2단계: SSH 키 생성

macOS / Linux

      터미널 (macOS / Linux)
      # Ed25519 알고리즘으로 SSH 키 생성 (권장)
ssh-keygen -t ed25519 -C "your_email@example.com"

# 실행하면 아래와 같은 질문이 나옵니다:
# Enter file in which to save the key (/Users/you/.ssh/id_ed25519): [Enter 키]
# Enter passphrase (empty for no passphrase): [비밀번호 입력 또는 Enter]
# Enter same passphrase again: [같은 비밀번호 또는 Enter]

# SSH Agent 시작
eval "$(ssh-agent -s)"

# macOS: Keychain에 SSH 키 등록 (재부팅 후에도 유지)
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

# Linux: SSH Agent에 키 등록
ssh-add ~/.ssh/id_ed25519
    

macOS 사용자: ~/.ssh/config 파일을 생성하면 터미널을 열 때마다 자동으로 키를 불러옵니다.

      ~/.ssh/config (macOS 권장 설정)
      Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
    

Windows

      Git Bash 또는 PowerShell
      # Ed25519 알고리즘으로 SSH 키 생성
ssh-keygen -t ed25519 -C "your_email@example.com"

# 동일하게 파일 경로와 비밀번호 질문이 나옵니다
# 기본값 그대로 Enter를 누르면 됩니다

# SSH Agent 서비스 시작 (PowerShell 관리자 권한)
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent

# SSH 키 등록
ssh-add $env:USERPROFILE\.ssh\id_ed25519
    

Windows SSH Agent 자동 시작: PowerShell을 관리자 권한으로 실행해야 SSH Agent 서비스를 설정할 수 있습니다. 시작 메뉴에서 "PowerShell"을 검색 → 우클릭 → "관리자로 실행"

3단계: GitHub에 공개키 등록

      공개키 복사 (OS별)
      # macOS — 클립보드에 복사
pbcopy < ~/.ssh/id_ed25519.pub

# Linux (xclip 설치 필요: sudo apt install xclip)
xclip -selection clipboard < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)
cat ~/.ssh/id_ed25519.pub | clip

# 또는 모든 OS에서 직접 출력 후 마우스로 복사
cat ~/.ssh/id_ed25519.pub
    

GitHub에 SSH 키 등록 절차
단계	GitHub 설정 절차
1	github.com/settings/keys에 접속 (로그인 필요)
2	"New SSH key" 버튼 클릭
3	Title: 알아보기 쉬운 이름 입력 (예: "MacBook Pro", "회사 데스크탑")
4	Key type: "Authentication Key" 선택 (기본값)
5	Key: 복사한 공개키를 붙여넣기
6	"Add SSH key" 클릭 → GitHub 비밀번호 확인

4단계: 연결 테스트

      터미널 (모든 OS 공통)
      # GitHub SSH 연결 테스트
ssh -T git@github.com

# 처음 연결 시 아래 메시지가 나오면 "yes" 입력:
# The authenticity of host 'github.com' can't be established.
# Are you sure you want to continue connecting? yes

# 성공 시 출력:
# Hi username! You've been authenticated, but GitHub does not provide shell access.
    

5단계: 기존 저장소를 SSH로 전환

이미 HTTPS로 clone한 저장소가 있다면 SSH URL로 변경할 수 있습니다.

      터미널 (모든 OS 공통)
      # 현재 원격 저장소 URL 확인
git remote -v
# origin  https://github.com/username/repo.git (fetch)

# SSH URL로 변경
git remote set-url origin git@github.com:username/repo.git

# 변경 확인
git remote -v
# origin  git@github.com:username/repo.git (fetch)
    

💡 새로 clone할 때: GitHub 저장소 페이지에서 "Code" 버튼 → "SSH" 탭을 선택하면 git@github.com:username/repo.git 형태의 URL을 복사할 수 있습니다.

SSH 키 관련 자주 발생하는 문제

SSH 키 관련 자주 발생하는 문제와 해결 방법
증상	원인	해결 방법
`Permission denied (publickey)`	SSH 키가 GitHub에 등록되지 않음 또는 Agent에 키가 로드되지 않음	`ssh-add ~/.ssh/id_ed25519`로 키 재등록. GitHub Settings에서 키 등록 여부 확인
`Could not open a connection to your authentication agent`	SSH Agent가 실행되지 않음	macOS/Linux: `eval "$(ssh-agent -s)"` Windows: SSH Agent 서비스 시작 (위 Windows 설정 참조)
재부팅 후 SSH 키를 다시 등록해야 함	SSH config 미설정 (macOS) 또는 Agent 자동 시작 미설정 (Windows)	macOS: `~/.ssh/config`에 `UseKeychain yes` 추가 Windows: SSH Agent 서비스를 Automatic으로 설정
`WARNING: UNPROTECTED PRIVATE KEY FILE!`	개인키 파일 권한이 너무 개방적	macOS/Linux: `chmod 600 ~/.ssh/id_ed25519` Windows: 파일 속성 → 보안 → 본인만 읽기/쓰기 권한 설정
Ed25519를 지원하지 않는 환경	매우 오래된 SSH 버전 사용	RSA 키로 대체: `ssh-keygen -t rsa -b 4096 -C "email@example.com"`

macOS에서 한 번에 설치하기

      터미널 (macOS) — Homebrew 방식
      # 1. Homebrew 설치 (없는 경우)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Python, Node.js, Git 한 번에 설치
brew install python node git

# 3. 설치 확인
python3 --version && node --version && git --version
    

Homebrew를 처음 설치하는 경우 (Apple Silicon Mac): Homebrew 설치 후 터미널에 표시되는 안내 메시지를 꼭 확인하세요. 보통 아래 명령을 실행해야 brew 명령이 동작합니다:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && eval "$(/opt/homebrew/bin/brew shellenv)"

macOS 공식 사이트 다운로드 방식 요약

터미널을 사용하지 않고 모두 공식 사이트에서 설치하는 방법입니다.

macOS 공식 사이트 다운로드 방식 요약
도구	다운로드 주소	설치 후 추가 작업
Python	python.org/downloads	Install Certificates.command 실행 필수 (위 인증서 설치 섹션 참조)
Node.js	nodejs.org	추가 작업 없음. LTS 버전 선택
Git	`xcode-select --install` 또는 git-scm.com	Xcode CLI 도구 설치가 가장 간편. 최신 버전이 필요하면 공식 사이트에서 다운로드

Windows에서 한 번에 설치하기

      PowerShell (관리자 권한)
      # 1. winget으로 한 번에 설치 (Windows 10/11)
winget install Python.Python.3
winget install OpenJS.NodeJS.LTS
winget install Git.Git

# 2. 터미널을 재시작한 후 확인
python --version && node --version && git --version
    

자주 발생하는 문제와 해결

설치 후 처음 사용할 때 가장 자주 마주치는 6가지 오류를 정리했습니다. 대부분 PATH 설정 누락, 인증서 미설치, 터미널 미재시작 중 하나가 원인입니다. 아래 표에서 증상을 찾아 해결 방법을 적용하세요.

자주 발생하는 설치 문제와 해결 방법
증상	원인	해결 방법
`python3: command not found`	PATH에 Python이 등록되지 않음	macOS: 터미널 재시작 또는 `export PATH="/usr/local/bin:$PATH"` Windows: Python 재설치 시 "Add to PATH" 체크
`[SSL: CERTIFICATE_VERIFY_FAILED]`	macOS에서 Python 인증서 미설치	`/Applications/Python\ 3.x/Install\ Certificates.command` 실행 (3.x를 설치 버전에 맞게 변경)
`pip install` 시 `Permission denied`	시스템 Python에 직접 설치 시도	`pip3 install --user 패키지명` 또는 가상환경(`python3 -m venv`) 사용
`node: command not found`	설치 후 터미널을 재시작하지 않음	터미널을 닫고 새로 열기. nvm 사용 시 `nvm use --lts`
macOS에서 `brew: command not found`	Homebrew PATH 미설정 (Apple Silicon Mac)	`eval "$(/opt/homebrew/bin/brew shellenv)"` 실행 후 `~/.zprofile`에 추가
macOS에서 앱 보안 경고	확인되지 않은 개발자 앱 차단	시스템 설정 → 개인정보 보호 및 보안 → 하단 "확인 없이 열기" 클릭 (macOS Ventura 이상 기준)

설치 체크리스트

설치 확인 체크리스트
확인 항목	명령어	기대 결과	상태
Antigravity 설치	앱 실행 가능	메인 채팅 화면 표시	☐
Python	`python3 --version`	Python 3.10+	☐
SSL 인증서 (macOS)	`python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"`	OpenSSL 버전 출력 (오류 없음)	☐
Node.js	`node --version`	v18+	☐
Git	`git --version`	git version 2.x	☐
npm / npx	`npx --version`	10.x+	☐
Git 사용자 설정	`git config --global user.name`	본인 이름 출력	☐
SSH 키 (GitHub)	`ssh -T git@github.com`	"Hi username! You've been authenticated..." 출력	☐

모두 설치했다면

축하합니다! 이제 Antigravity에서 "Python으로 데이터 분석해줘", "React 웹앱 만들어줘", "GitHub에 코드 올려줘"까지 모든 요청이 바로 동작합니다. 다음 섹션에서 Antigravity 앱 설치와 시스템 요구사항을 확인하세요.

설치 후 동작 확인 — 빠른 검증 스크립트

아래 스크립트를 터미널에서 실행하면 모든 도구의 설치 상태를 한 번에 확인할 수 있습니다.

      터미널 (macOS / Linux / Windows Git Bash)
      #!/bin/bash
# Antigravity 개발 환경 빠른 검증 스크립트
echo "=== Antigravity 개발 환경 점검 ==="

# Python 확인
python3 --version 2>/dev/null && echo "✅ Python OK" || echo "❌ Python 미설치"
python3 -c "import ssl; print('✅ SSL OK: ' + ssl.OPENSSL_VERSION)" 2>/dev/null || echo "⚠️  SSL 인증서 확인 필요"

# Node.js 확인
node --version 2>/dev/null && echo "✅ Node.js OK" || echo "❌ Node.js 미설치"

# Git 확인
git --version 2>/dev/null && echo "✅ Git OK" || echo "❌ Git 미설치"

# uv 확인 (선택)
uv --version 2>/dev/null && echo "✅ uv OK" || echo "ℹ️  uv 미설치 (선택)"

# GitHub SSH 확인 (선택)
ssh -T git@github.com 2>&1 | grep -q "authenticated" && echo "✅ GitHub SSH OK" || echo "ℹ️  GitHub SSH 미설정 (선택)"

echo "=== 점검 완료 ===
    

Windows 사용자: 위 스크립트는 Git Bash 또는 WSL에서 실행하세요. PowerShell에서는 각 명령을 개별적으로 실행하거나, python (python3 대신)을 사용해야 할 수 있습니다.

터미널에서 Antigravity IDE 실행 — `agy-ide` 명령어

Antigravity IDE를 설치하면 터미널에서 agy-ide 명령어로 폴더를 바로 열 수 있습니다. GUI에서 File → Open Folder를 거치지 않아도 되어 개발자 워크플로에 편리합니다.

2026-05 명령 이름 변경: 이 명령은 원래 agy였으나, 2026-05-19 I/O 발표 이후 신규 Antigravity CLI가 agy 이름을 차지하면서 IDE 런처는 agy-ide로 개명됐습니다. 두 명령의 역할은 다음과 같이 다릅니다.

agy-ide — Antigravity IDE(VS Code 기반 에디터) 폴더 열기. 이 페이지의 주제.
agy — Antigravity CLI(터미널 에이전트). 자세한 내용은 Antigravity CLI 페이지.

      터미널
      # 현재 디렉토리를 Antigravity IDE로 열기
agy-ide .

# 특정 폴더 열기
agy-ide /path/to/project

# 새 빈 창 열기
agy-ide --new-window
    

agy-ide 명령어가 없을 때: macOS에서는 설치 후 자동으로 /usr/local/bin/agy-ide에 추가됩니다. 인식되지 않는다면 터미널을 재시작하거나, Antigravity IDE에서 Cmd+Shift+P → "Shell Command: Install 'agy-ide' command in PATH"로 수동 설치합니다.

Linux 사용자 주의: 일부 배포판은 바이너리를 antigravity로 설치합니다. 이 경우 sudo ln -s /usr/bin/antigravity /usr/local/bin/agy-ide로 심볼릭 링크를 만들면 됩니다.

agy-ide 체크리스트 항목
확인 항목	명령어	기대 결과
agy-ide 설치 확인	`which agy-ide`	`/usr/local/bin/agy-ide` 또는 설치 경로 출력
버전 확인	`agy-ide --version`	설치된 Antigravity IDE 버전 출력
Antigravity CLI(별개 도구) 확인	`which agy`	`~/.local/bin/agy` 등 — CLI 사용 안 하면 비어 있어도 정상

부록: Python 직접 설치 (선택) #

📌 대부분의 사용자는 이 섹션을 건너뛰어도 됩니다. uv를 설치하면 uv python install 3.12 한 줄로 Python을 자동 설치·관리할 수 있어, 시스템에 Python을 직접 설치할 필요가 없습니다. 이 섹션은 다음 두 경우에만 참고하세요.

uv 없이 시스템 Python을 직접 설치하려는 경우 (회사 정책 등으로 uv 사용 불가)
Python을 글로벌하게 사용해야 하는 경우 (Jupyter Lab을 시스템 전체에서 호출, 다른 도구가 시스템 Python에 의존 등)

데이터 분석, 머신러닝, 자동화 스크립트 등 대부분의 작업에 사용되는 Python을 시스템 전체에 직접 설치하는 방법입니다.

Python 버전 호환성 매트릭스

Python 버전별 주요 라이브러리 호환성 및 권장 여부
Python 버전	상태	pandas	scikit-learn	권장 여부
3.13.x	최신	2.2+	1.5+	✅ 권장 (최신 기능)
3.12.x	안정	2.0+	1.3+	✅ 권장 (호환성 우수)
3.11.x	지원 중	2.0+	1.2+	✅ 사용 가능
3.10.x	지원 중 (최소 요구)	1.5+	1.1+	⚠️ 최소 버전 (업그레이드 권장)
3.9 이하	지원 종료 예정	-	-	❌ 사용 비권장

방법 A: 공식 사이트에서 다운로드 (모든 OS 공통, 초보자 추천)

Python 공식 사이트 다운로드 설치 단계
단계	내용	상세 설명
1	공식 사이트 접속	python.org/downloads에 접속합니다
2	설치 파일 다운로드	노란색 "Download Python 3.x.x" 버튼 클릭. macOS는 macOS 64-bit universal2 installer 선택, Windows는 Windows installer (64-bit) 선택
3	설치 프로그램 실행	다운로드된 `.pkg`(macOS) 또는 `.exe`(Windows) 파일 더블클릭
4	설치 옵션 확인	Windows: 첫 화면에서 "Add python.exe to PATH" 반드시 체크! macOS: 기본 옵션 그대로 "계속" 클릭
5	설치 완료	"Install Now"(Windows) 또는 "설치"(macOS) 클릭 후 완료 대기

macOS 인증서 설치 (중요!)
Python 공식 설치 프로그램으로 설치한 경우, SSL 인증서를 별도로 설치해야 합니다. 이 단계를 건너뛰면 pip install이나 웹 요청 시 SSL 인증서 오류가 발생합니다.

      macOS 인증서 설치 (공식 설치 후 필수)
      # 방법 1: Finder에서 설치
# /Applications/Python 3.x/ 폴더를 열고
# "Install Certificates.command" 파일을 더블클릭

# 방법 2: 터미널에서 직접 실행
/Applications/Python\ 3.x/Install\ Certificates.command
# (3.x를 설치한 버전에 맞게 변경, 예: 3.12, 3.13)
    

인증서 설치가 필요한 이유: macOS에 내장된 Python은 시스템 인증서를 사용하지만, 공식 설치 프로그램의 Python은 자체 인증서 저장소를 사용합니다. Install Certificates.command를 실행하면 certifi 패키지를 설치하고 시스템 인증서를 연결합니다. 이 단계를 빠뜨리면 urllib, requests, pip 등에서 [SSL: CERTIFICATE_VERIFY_FAILED] 오류가 발생합니다.

방법 B: Homebrew로 설치 (macOS 터미널 사용자)

Homebrew로 설치하면 인증서가 자동으로 설정되며, 버전 업데이트도 간편합니다.

      터미널 (macOS)
      # Homebrew가 없다면 먼저 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Python 설치
brew install python

# Homebrew Python은 인증서가 자동 설정됨 (별도 작업 불필요)
    

방법 C: 패키지 관리자로 설치

운영체제별 Python 패키지 관리자 설치 명령어
운영체제	명령어	비고
Windows	`winget install Python.Python.3`	PowerShell(관리자)에서 실행. PATH 자동 설정됨. 최신 3.x 설치
Linux (Ubuntu/Debian)	`sudo apt update && sudo apt install python3 python3-pip python3-venv`	대부분 이미 설치되어 있음. `python3-venv`는 가상환경용
Linux (Fedora)	`sudo dnf install python3 python3-pip`	Fedora/RHEL/CentOS 계열

      설치 확인 (모든 OS 공통)
      # Python 버전 확인 (3.10 이상 권장)
python3 --version
# 출력 예: Python 3.x.x (설치 시점에 따라 다름)

# pip (패키지 관리자) 확인
pip3 --version
# 출력 예: pip 24.x from /.../site-packages/pip

# SSL 인증서 정상 여부 확인
python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
# 출력 예: OpenSSL 3.2.1 30 Jan 2024

# Windows에서는 python3 대신 python 사용
python --version
    

Python으로 할 수 있는 것: pandas/numpy 데이터 분석, matplotlib/seaborn 시각화, scikit-learn 머신러닝, Flask/FastAPI 웹 서버, 웹 스크래핑, 파일 자동화 등

PATH 환경변수 주의 (특히 Windows / macOS 공식 설치 시): Python 설치 후 python3 명령이 인식되지 않는다면 PATH 등록이 누락된 것입니다.

Windows: 설치 마법사에서 "Add Python to PATH" 체크박스를 반드시 선택하세요. 이미 설치했다면 제어판 → 시스템 → 고급 시스템 설정 → 환경 변수에서 Python 설치 경로를 수동으로 추가하세요.
macOS (공식 .pkg 설치): 설치 후 /Applications/Python\ 3.x/Update\ Shell\ Profile.command를 실행하거나, ~/.zshrc에 export PATH="/Library/Frameworks/Python.framework/Versions/3.x/bin:$PATH"를 추가하세요.
공통: PATH 수정 후에는 반드시 터미널을 완전히 닫고 새로 열어야 적용됩니다.

Python 설치 방법 비교 표
설치 방법 비교	공식 사이트 다운로드	Homebrew (macOS)	패키지 관리자
난이도	쉬움 (GUI 클릭)	보통 (터미널 명령)	보통 (터미널 명령)
인증서 설정	수동 설치 필요	자동	자동
업데이트	새 버전 직접 다운로드	`brew upgrade python`	`apt upgrade` 등
여러 버전 관리	어려움	가능	가능 (pyenv 권장)
추천 대상	프로그래밍 처음 시작하는 분	macOS 개발자	Linux 사용자

💡 다시 강조: 위 작업이 번거롭다면 uv 설치로 돌아가세요. uv 한 도구로 Python 설치 + 가상환경 + 패키지 관리 + 도구 실행이 모두 해결됩니다.

부록: Firebase Studio에서 Antigravity로 마이그레이션 공식 문서 #

Firebase Studio는 2027년 종료가 예고된 상태로, Google이 후속 워크플로로 Antigravity를 권장합니다. Firebase Studio의 프로젝트를 그대로 가져와 작업을 이어갈 수 있도록 공식 마이그레이션 경로가 마련되어 있습니다.

주요 일정 (2026년 기준 공지):

2026-06-22 — Firebase Studio 신규 워크스페이스 생성 중단
2027-03-22 — Firebase Studio 종료, 남은 데이터 영구 삭제

현재 사용 중인 프로젝트가 있다면 이 기간 안에 마이그레이션을 마치세요. 최신 일정은 Firebase 공식 안내를 확인합니다.

언제 Antigravity로 옮기면 좋은가

Firebase Studio의 Code View를 주로 사용했다 — 로컬 IDE 흐름이 익숙하다는 신호
코드 베이스에 직접 손대는 작업이 많다 — Antigravity의 에이전트형 환경이 자연스럽게 맞물림
로컬 워크스테이션 자원을 활용하고 싶다 — 클라우드 IDE 의존을 줄이고 싶을 때
Gemini 모델·Agent Skills·Browser Subagent 등 본 튜토리얼이 다루는 기능이 필요한 경우

마이그레이션 흐름 — 3단계

Firebase Studio에서 프로젝트 추출 — 워크스페이스를 zip 또는 git 저장소로 내려받음. (Firebase Studio UI의 다운로드/Export 기능 활용)
로컬에 압축 해제·git 초기화 — Antigravity가 인식할 수 있는 일반 폴더 구조로 풀어 둡니다.
Antigravity IDE에서 폴더 열기 — File → Open Folder 또는 터미널에서 agy-ide 폴더경로(2026-05 이전 옛 이름은 agy). Agent 패널에서 Gemini Flash 모델을 선택하고 "이 프로젝트를 Antigravity 환경에 맞게 점검·정리해 줘"라고 요청하면 에이전트가 누락된 의존성·런타임을 안내합니다.

참고 자료: Google이 공식 코드랩으로 "How to Migrate from Firebase Studio to Antigravity"를 제공합니다. 단계별 캡처와 함께 실습 가능. Antigravity는 Firebase Hosting·Firestore·Authentication 등 핵심 Firebase 서비스를 그대로 사용할 수 있어 코드 변경 없이 동작합니다.

마이그레이션 직후 점검 항목:

.env·service-account.json 같은 비밀 파일이 정상 위치에 있는지 확인. Permissions의 deny 규칙도 한 번 점검.
Firebase Studio가 자동 주입하던 환경변수는 로컬에서 별도 설정 필요. .env 또는 direnv·mise 등으로 관리.
패키지 매니저 lock 파일이 함께 옮겨졌는지 확인. 없으면 최소 공개 기간 정책 점검 후 새로 생성.

개발 환경 설치 가이드