VS Code 설치와 기본 사용법: 플랫폼별 공식 설치부터 첫 프로젝트 실행까지

결론 요약과 플랫폼별 설치 파일

Windows는 User Installer(x64/Arm64 .exe)를 내려받아 실행하면 PATH에 code 명령이 자동 등록됩니다. macOS는 Universal .dmg를 열어 Applications 폴더로 드래그한 뒤, 명령 팔레트(P)에서 'Shell Command: Install 'code' command in PATH'를 실행해야 터미널에서 code 명령이 작동합니다.

Linux(Debian/Ubuntu)는 .deb 파일을 내려받아 sudo apt install ./<file>.deb로, Fedora/RHEL은 .rpm 파일을 sudo dnf install ./<file>.rpm으로 설치합니다. 이 방식으로 설치하면 apt/dnf 저장소가 함께 구성돼 자동 업데이트가 적용됩니다. 플랫폼별 최신 설치 파일은 https://code.visualstudio.com/download 에서 확인합니다.

첫 프로젝트 폴더 열기와 터미널 확인

1. VS Code를 실행한 뒤 파일 메뉴에서 '폴더 열기'를 선택하거나, 터미널에서 code .을 입력해 현재 디렉터리를 워크스페이스로 엽니다.
2. 왼쪽 활동 막대의 탐색기 아이콘(또는 Ctrl+Shift+E)을 눌러 파일 트리가 표시되는지 확인합니다.
3. 터미널 메뉴에서 '새 터미널'(`Ctrl+Shift+``)을 열어 프롬프트가 나타나는지 확인합니다.
4. 탐색기에서 마우스 오른쪽 버튼 → '새 파일'로 hello.py를 만들고 print("Hello VS Code")를 입력한 뒤 Ctrl+S로 저장합니다.
5. 터미널에서 python hello.py를 실행해 Hello VS Code가 출력되면 실행 환경 설정이 끝난 것입니다.

필수 확장 프로그램 설치와 설정 동기화

확장 프로그램 화면(Ctrl+Shift+X)의 검색창에 python을 입력하고 Microsoft 공식 Python 확장(게시자: Microsoft, ID: ms-python.python)을 설치합니다. 이어서 GitLens(게시자: GitKraken, ID: eamodio.gitlens)를 설치하면 Git 이력·블레임·코드 렌즈가 에디터에 표시됩니다. 설정 동기화는 왼쪽 아래 계정 아이콘 또는 관리(톱니) 메뉴에서 'Backup and Sync Settings...'를 선택하고 GitHub 또는 Microsoft 계정으로 로그인하면 켜지며, 확장·설정·키바인딩이 기기 간에 공유됩니다.

특정 확장을 동기화에서 제외하려면 확장을 마우스 오른쪽 버튼으로 클릭한 뒤 '설치(동기화 안 함)'를 선택합니다.

GitHub Copilot Free 활성화 절차

제목 표시줄의 '로그인' 또는 상태 표시줄의 Copilot 아이콘을 클릭해 'AI 기능 사용'을 선택합니다. GitHub 계정으로 로그인하면 기존 Copilot 구독이 자동 적용되고, 구독이 없으면 Copilot Free 플랜에 가입돼 월간 인라인 제안과 AI 크레딧이 제공됩니다.

Copilot Chat(Ctrl+Alt+I)에서 자연어로 작업을 설명하면 에이전트가 파일 생성·편집·터미널 명령 실행을 제안합니다. 자체 LLM API 키를 사용하려면 채팅의 언어 모델 선택기에서 'Manage Language Models'(톱니 아이콘) 또는 명령 팔레트의 'Chat: Manage Language Models'를 열어 공급자와 키를 등록합니다.

설치 방식과 확장 설치의 제한 사항

첫째, Windows에서 System Installer(관리자 권한 필요)를 선택하면 Program Files 아래에 모든 사용자용으로 설치되고, User Installer는 현재 사용자 프로필(%LOCALAPPDATA%)에만 설치됩니다. 둘째, 버전 1.97부터는 확장 프로그램을 처음 설치할 때 서드파티 게시자 신뢰 확인 대화상자가 나타나며, 신뢰를 선택하지 않으면 설치가 진행되지 않습니다. 신뢰 상태를 나중에 바꾸려면 명령 팔레트에서 'Extensions: Manage Trusted Extensions Publishers'를 실행합니다.

code 명령 오류 원인과 조치

증상은 터미널에서 code . 입력 시 '명령을 찾을 수 없음' 또는 'code is not recognized' 오류가 표시되는 것이며, 이 오류가 나타나면 PATH 등록 여부를 먼저 확인합니다. Windows는 User Installer 설치 시 PATH 추가 옵션이 해제됐는지, macOS는 'Shell Command: Install 'code' command in PATH' 명령을 실행했는지 확인합니다. 조치는 Windows의 경우 설치 프로그램 재실행 → 'PATH에 추가' 체크 → 재부팅이고, macOS는 명령 팔레트에서 해당 명령을 다시 실행합니다.

이 조치로 해결되지 않으면 공식 문서의 '설치 후 code 명령 설정' 페이지를 참조해 PATH를 직접 편집해야 합니다.

설치 완료 확인 항목

• VS Code 창이 열리고 탐색기·검색·소스 제어·확장·계정 아이콘 5개가 활동 막대에 모두 표시
• 터미널(Ctrl+Shift+``)에서 code --version` 실행 시 버전 번호(예: 1.97.0)가 출력
• Python 확장 설치 후 hello.py 저장 시 하단 상태 표시줄에 'Python 3.x.x' 인터프리터가 감지
• GitHub 계정 로그인 후 상태 표시줄 Copilot 아이콘이 활성화(회색→색상)되고 Chat 창이 열림
• 설정 동기화 아이콘이 '동기화' 상태(구름에 체크 표시)로 표시

설치할 수 없는 환경의 대안과 지원 요청

브라우저만 사용할 수 있는 환경에서는 https://vscode.dev 에서 설치 없이 편집·Git 커밋·일부 확장을 사용할 수 있습니다. 최신 기능을 미리 확인하려면 Insiders 빌드(매일 배포)를 별도로 설치해 Stable과 함께 실행합니다. 기업 환경에서 프록시·방화벽 때문에 마켓플레이스 접근이 차단되면 IT 관리자에게 https://marketplace.visualstudio.com 및 https://*.gallery.vsassets.io 허용을 요청해야 합니다.

공식 문서로 해결되지 않는 설치 오류는 https://github.com/microsoft/vscode/issues 에서 기존 이슈를 검색한 뒤 새로 등록합니다.

사용자 조건별 설치 방식

사용자 조건별 권장 설치 방식과 다음 조치를 비교한 표입니다.

최소 명령 모음

# Windows (PowerShell, User Installer 설치 후)

code .
code --version

# macOS (code 명령 PATH 등록 후)

code .
code --version

# Ubuntu/Debian

sudo apt update && sudo apt install ./code_*.deb
code .

# Fedora/RHEL

sudo dnf install ./code-*.rpm
code .

# 첫 Python 파일 생성 및 실행

echo 'print("Hello VS Code")' > hello.py
python hello.py

보안 주의 사항

GitHub Copilot 로그인 시 개인 액세스 토큰(PAT)을 설정 파일에 하드코딩하지 않고 OAuth 플로우만 사용합니다. 확장 프로그램 설치 시 서드파티 게시자 신뢰 대화상자에서 '신뢰함'을 선택하기 전에 게시자 이름과 다운로드 수를 확인합니다. 설정 동기화 전에 settings.json에 API 키, 데이터베이스 비밀번호, 인증서 경로가 포함되지 않았는지 검토합니다.

기업 기기에서는 조직 정책으로 확장 마켓플레이스 접근이 차단될 수 있으므로, 설치 전에 IT 관리자에게 확인합니다.

FAQ

Q: Windows에서 User Installer와 System Installer 중 무엇을 선택해야 하나요? A: 관리자 권한이 없고 본인 계정만 사용하는 경우에는 User Installer를, 여러 사용자가 공유하거나 시스템 전체에 배포하는 경우에는 System Installer를 사용해야 합니다. User Installer는 %LOCALAPPDATA%\Programs\Microsoft VS Code에, System Installer는 C:\Program Files\Microsoft VS Code에 설치됩니다.

Q: macOS에서 code 명령이 zsh에서 작동하지 않습니다. A: 명령 팔레트에서 'Shell Command: Install 'code' command in PATH'를 실행한 뒤 셸을 재시작(exec $SHELL)하거나 터미널을 다시 엽니다.

Q: 프록시 환경에서 확장 마켓플레이스가 열리지 않습니다. A: VS Code 설정(Ctrl+,)에서 http.proxy와 http.proxyStrictSSL을 구성하거나, 환경 변수 HTTP_PROXY/HTTPS_PROXY를 설정한 뒤 VS Code를 재시작합니다. 자세한 내용은 공식 문서 'Proxy server support' 페이지에 있습니다.