5부 · 개발 도구 세팅
← 이전: 프로그램은 어떻게 도는가 · 목차 · 다음: 막혔을 때 빠져나오는 법 →
이제 실제로 코드를 쓰고 돌릴 도구를 깝니다. 세 가지를 준비합니다: ① 코드를 편하게 쓰는 에디터, ② 코드를 실행해 줄 Python, ③ 프로젝트별로 패키지를 깔끔히 관리하는 가상환경과 패키지 설치(pip). 이 챕터를 끝내면 RAG 안내서 첫 코드를 돌릴 환경이 완성됩니다.
버전은 빠르게 바뀝니다. 이 글은 Python 3.14 시대(2026년 중반) 기준이며, 설치 화면 문구가 조금 다를 수 있습니다. 핵심 개념(가상환경·pip·PATH)은 버전이 바뀌어도 그대로입니다. 항상 공식 사이트의 최신 안내를 함께 보세요.
5.1 코드 에디터 설치 — VS Code
코드는 메모장으로도 쓸 수 있지만, 색 구분·자동완성·내장 터미널이 있는 코드 에디터를 쓰면 훨씬 수월합니다. 입문자에게 가장 무난한 선택은 Visual Studio Code(줄여서 VS Code)입니다. 무료이고, Windows·macOS·Linux 모두 됩니다.
설치 순서:
- 브라우저에서 공식 사이트
https://code.visualstudio.com에 들어가 자기 OS용 설치 파일을 받습니다. - 받은 설치 파일을 실행해 안내대로 설치합니다. (Windows 설치 중 "PATH에 추가" 옵션이 보이면 체크해 두세요. 그래야 터미널에서
code .명령으로 폴더를 열 수 있습니다.) - VS Code를 열고, 왼쪽의 확장(Extensions) 아이콘에서 Python 확장(Microsoft 제공)을 설치합니다. 이게 Python 코드의 색 구분·실행·디버깅을 도와줍니다.
콜아웃 · VS Code의 내장 터미널
VS Code 상단 메뉴에서 "터미널(Terminal) → 새 터미널(New Terminal)"을 열면, 에디터 안에 3부에서 배운 터미널이 그대로 뜹니다. 게다가 현재 열어둔 폴더가 곧 cwd가 됩니다. 즉 "엉뚱한 폴더에서 실행" 함정을 자연스럽게 피하게 됩니다. 앞으로 작업은 "VS Code로 프로젝트 폴더를 열고 → 내장 터미널을 쓰는" 흐름을 권합니다.
5.2 Python 설치 — 가장 중요한 체크박스 하나
4부에서 봤듯, Python 코드를 돌리려면 코드를 해석해 줄 python 프로그램(인터프리터)이 필요합니다. 이걸 깝니다.
Windows
- 공식 사이트
https://www.python.org→ Downloads에서 Windows용 최신 안정판(예: 3.14.x)을 받습니다. 대부분 64비트 시스템이므로 64비트 설치 파일을 받으면 됩니다. - 받은
.exe를 실행합니다. - 가장 중요: 설치 첫 화면 맨 아래의 "Add python.exe to PATH"(또는 "Add Python to PATH") 체크박스를 반드시 켜세요. 그런 다음 "Install Now"를 누릅니다.
이 체크박스가 왜 그렇게 중요한가요? 4.5에서 배운 PATH 때문입니다. 이걸 켜야 터미널 어디서든 python이라고만 쳐도 OS가 설치된 Python을 찾습니다. 안 켜면 거의 100% 'python'은(는) ... 인식할 수 없습니다(command not found) 오류를 만납니다. 입문자가 가장 많이 빠지는 함정이 바로 이것입니다.
이미 체크 안 하고 설치했다면? 설치 파일을 다시 실행해 "Modify"에서 PATH 옵션을 켜거나, Python을 지웠다 다시 설치하면서 체크하는 게 가장 깔끔합니다.
macOS
https://www.python.org 에서 macOS용 설치 파일을 받아 설치하면 보통 PATH가 자동 설정됩니다. macOS에는 옛 시스템용 Python이 섞여 있을 수 있어, 명령은 python 대신 python3를 쓰는 경우가 많습니다.
Linux
대개 Python이 이미 깔려 있습니다. 배포판 패키지 관리자로 보강합니다(예: 데비안/우분투 계열은 sudo apt install python3 python3-venv python3-pip). 명령은 python3를 씁니다.
설치 확인
새 터미널을 열고(설치 후엔 꼭 새 창을 여세요 — PATH 변경이 반영되려면 필요합니다) 아래를 칩니다.
# Windows: 아래 셋 중 되는 것을 쓰면 됩니다 python --version py --version # mac/Linux python3 --version
Python 3.14.6
처럼 버전 숫자가 나오면 성공입니다. Windows에서 py는 여러 Python 버전을 깔았을 때 버전을 골라 실행해 주는 런처(launcher)라, python이 안 될 때 py가 되는 경우가 종종 있습니다. 둘 다 안 되면 PATH 문제이니 위 콜아웃을 보세요.
pip(패키지 설치 도구)도 함께 깔립니다. 확인:
# Windows pip --version # 안 되면 py -m pip --version # mac/Linux pip3 --version
5.3 가상환경 — 프로젝트마다 깨끗한 작업대
여기서부터가 입문자가 잘 모르지만 반드시 알아야 하는 부분입니다.
Python으로 일하다 보면 외부 코드 묶음, 즉 패키지(package)를 많이 설치하게 됩니다(RAG라면 임베딩·벡터 검색 관련 패키지들). 그런데 이걸 시스템 전체에 막 깔면 문제가 생깁니다. A 프로젝트는 어떤 패키지의 1.0 버전이 필요한데 B 프로젝트는 2.0이 필요하면, 둘이 충돌합니다.
해결책이 가상환경(virtual environment, 줄여서 venv)입니다. 프로젝트마다 격리된 "전용 작업대"를 만들어, 그 안에만 패키지를 깝니다. 프로젝트끼리 서로 간섭하지 않습니다.
flowchart TB
SYS["시스템 Python<br/>(건드리지 않고 깨끗하게)"]
SYS --> A["프로젝트 A의 venv<br/>패키지 1.0 설치"]
SYS --> B["프로젝트 B의 venv<br/>패키지 2.0 설치"]
SYS --> C["프로젝트 C의 venv<br/>또 다른 조합"]
classDef sys fill:#E6D6FF,stroke:#7C4DBC,color:#000
classDef env fill:#C8F0E8,stroke:#2BA88E,color:#000
class SYS sys
class A,B,C env
가상환경 쓰는 흐름은 "만들기 → 켜기(활성화) → 그 안에서 설치·실행 → 끝나면 끄기"입니다.
① 만들기
프로젝트 폴더로 이동한 뒤(cd로!), 그 안에 .venv라는 가상환경을 만듭니다.
# 먼저 프로젝트 폴더로 이동 (예시) cd Documents\rag-project # 가상환경 생성 (Windows) python -m venv .venv # python이 안 되면: py -m venv .venv # mac/Linux python3 -m venv .venv
이러면 폴더 안에 .venv라는 새 폴더가 생깁니다. 그 안에 이 프로젝트 전용 Python과 패키지 저장 공간이 들어 있습니다.
② 켜기 (활성화)
만든다고 자동으로 켜지진 않습니다. 매번 활성화(activate)해야 합니다.
# Windows PowerShell .\.venv\Scripts\Activate.ps1 # mac/Linux source .venv/bin/activate
활성화되면 프롬프트 앞에 (.venv)가 붙습니다.
(.venv) PS C:\Users\나의계정\Documents\rag-project>
이 (.venv) 표시가 "지금 이 가상환경 작업대 위에 서 있다"는 신호입니다. 이게 보이는 동안 설치하는 패키지는 전부 이 프로젝트 안에만 들어갑니다.
콜아웃 · Windows에서 활성화가 막힐 때 (실행 정책 오류)
PowerShell에서Activate.ps1을 실행하면 보안 설정 때문에 "이 시스템에서 스크립트를 실행할 수 없습니다" 류의 오류가 날 수 있습니다. 이때는 PowerShell에서 아래를 한 번 실행해 현재 사용자에 한해 스크립트 실행을 허용한 뒤 다시 활성화하세요.
```
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```
보안이 걱정된다면, 이 명령의 의미를 6부의 "검색하는 법"으로 한 번 찾아보는 것도 좋은 연습입니다.
③ 끄기 (비활성화)
작업이 끝나 가상환경에서 나오려면:
deactivate
(.venv) 표시가 사라집니다. 터미널 창을 닫아도 자동으로 풀립니다. 다음에 다시 작업할 땐 ②번 활성화만 다시 하면 됩니다(만들기는 한 번만).
5.4 패키지 설치 — pip
가상환경을 켠 상태에서(프롬프트에 (.venv)가 보이는지 꼭 확인!) 패키지를 깝니다. 도구는 pip입니다.
# 패키지 하나 설치 (예시: requests) pip install requests # 특정 버전 지정 pip install requests==2.32.0 # 지금 깔린 패키지 목록 보기 pip list
설치된 패키지는 코드에서 import로 불러 씁니다.
# app.py import requests response = requests.get("https://httpbin.org/get") print("상태 코드:", response.status_code)
# 실행 (가상환경이 켜진 상태에서) python app.py
콜아웃 ·pip install이 실패하거나 "권한 없음"이 뜬다면
십중팔구 가상환경을 안 켜고 시스템 전체에 깔려다가 권한에 막힌 경우입니다. 프롬프트에(.venv)가 보이는지 먼저 확인하세요. 가상환경을 켜면 권한 문제 없이 그 폴더 안에 깔립니다. 4부에서 본 "여기서 2부가 다시 등장한다"처럼, 입문 단계 오류는 대부분 앞 챕터 개념의 누락입니다.
requirements.txt — 필요한 패키지 목록
프로젝트가 어떤 패키지를 쓰는지 한 파일에 적어두면, 다른 사람(또는 미래의 나)이 똑같은 환경을 한 번에 만들 수 있습니다. 관례적으로 requirements.txt라는 파일에 적습니다.
# requirements.txt requests==2.32.0
이 목록을 한꺼번에 설치:
pip install -r requirements.txt
RAG 안내서의 실습 프로젝트도 이런 식으로 의존성을 모아 관리합니다. "복붙하면 돌아간다"의 비결 중 하나가 바로 이 파일입니다.
버전 번호와 "버전 고정"이 중요한 이유
requests==2.32.0의 ==2.32.0은 정확히 그 버전을 쓰라는 뜻입니다(이를 버전 고정/pinning이라 합니다). 버전 번호는 보통 2.32.0처럼 점 세 자리이고, 대략 이런 의미입니다.
| 자리 | 이름 | 올라가면 |
|---|---|---|
2.x.x | 메이저 | 큰 변화, 예전 코드가 깨질 수 있음 |
x.32.x | 마이너 | 기능 추가, 보통 호환됨 |
x.x.0 | 패치 | 버그 수정, 거의 항상 호환됨 |
왜 굳이 버전을 고정할까요? 패키지는 계속 업데이트되는데, 어느 날 메이저 버전이 올라가며 함수 이름이 바뀌면 어제 잘 돌던 코드가 오늘 갑자기 깨질 수 있기 때문입니다. RAG 생태계(임베딩·검색 라이브러리)는 특히 빠르게 바뀌어서, 안내서의 코드가 안 돌면 "버전 차이"가 흔한 원인입니다.
콜아웃 · 안내서 코드가 안 돌 때 가장 먼저 의심할 것
복붙한 RAG 코드가 이상한 오류를 내면, ① 안내서가 명시한 패키지 버전과 내 설치 버전이 같은지(pip list로 확인), ② 파이썬 버전이 맞는지(python --version)를 먼저 보세요. 라이브러리가 새 버전에서 사용법을 바꾼 경우, 그 라이브러리의 공식 문서 최신판을 확인하는 게 정답입니다(6부의 검색법). 이래서 RAG 안내서들이 "이 글은 어느 버전 기준"이라고 밝히는 것입니다.
(참고) 주피터 노트북 — 많은 RAG 튜토리얼의 형식
RAG 튜토리얼은 .py 파일 대신 주피터 노트북(Jupyter Notebook, 확장자 .ipynb) 형식인 경우가 많습니다. 노트북은 코드를 셀(cell) 단위로 나눠 한 칸씩 실행하고 결과(표·그래프 포함)를 바로 아래에서 보는 방식이라, 실험과 학습에 편합니다. VS Code에 Python 확장을 깔면 .ipynb 파일을 바로 열어 쓸 수 있고, 가상환경(5.3)을 그 노트북의 실행 환경으로 골라줄 수 있습니다. 지금 깊이 알 필요는 없고, ".ipynb를 만나면 셀을 위에서부터 차례로 실행하는 거구나" 정도만 기억하면 됩니다.
5.5 Git — 코드의 "되돌리기"와 백업 (첫 만남)
여기까지 오면 곧 Git이라는 단어를 만나게 됩니다. 많은 개발 가이드가 "저장소를 클론하세요", "커밋하세요"로 시작하는데, Git이 뭔지 모르면 그 첫 줄에서 막힙니다. 이 절은 그 막힘을 없애는 최소한의 소개입니다(자세한 사용법은 별도의 Git 가이드에서 다룹니다).
Git은 코드의 변경 이력을 기록하는 도구입니다. 문서 작업의 "버전 기록"이나 게임의 "세이브 포인트"를 떠올리면 됩니다. 언제든 과거 상태로 되돌릴 수 있고, 여러 사람이 같은 코드를 안전하게 함께 고칠 수 있게 해줍니다. Git이 관리하는 프로젝트 폴더 하나를 저장소(repository, 줄여서 repo)라고 부릅니다.
flowchart LR
A["코드를 고침<br/>(작업 중)"] --> B["커밋(commit)<br/>= 지금 상태를 세이브"]
B --> C["이력에 기록됨<br/>(나중에 되돌리기 가능)"]
B -.선택.-> D["GitHub 등에 푸시<br/>= 인터넷에 백업·공유"]
classDef work fill:#FFF3B0,stroke:#C9A227,color:#000
classDef save fill:#C8F0E8,stroke:#2BA88E,color:#000
classDef good fill:#D7F2C8,stroke:#5BA63B,color:#000
classDef remote fill:#CDE7FF,stroke:#3B82C4,color:#000
class A work
class B save
class C good
class D remote
용어 몇 개만 미리 풀어둡니다. 커밋(commit)은 "지금까지의 변경을 한 묶음으로 기록(세이브)"하는 것, GitHub은 그 저장소를 인터넷에 올려 백업·공유하는 대표적인 서비스, 클론(clone)은 남의(또는 내) GitHub 저장소를 내 컴퓨터로 통째로 복제해 오는 것입니다. RAG 안내서가 "이 저장소를 클론하세요"라고 하면, Git으로 그 코드를 내려받으라는 뜻입니다.
설치와 확인
- Windows:
https://git-scm.com/download/win에서 설치 파일을 받아 설치합니다(대부분 기본 옵션 그대로 두면 되고, "Add to PATH"는 기본으로 켜져 있습니다). macOS는 보통git을 처음 실행하면 설치를 안내하거나 Homebrew로 깔고, Linux는sudo apt install git등으로 깝니다. - 새 터미널을 열고 확인합니다(5.2에서처럼 설치 후엔 새 창이 필요합니다).
git --version
git version 2.54.0.windows.1
처럼 버전이 나오면 성공입니다. 처음 한 번은 내 이름과 이메일을 등록해 둡니다(커밋에 기록될 정보입니다).
git config --global user.name "내 이름" git config --global user.email "[email protected]"
.gitignore — 올리면 안 되는 것 막기
저장소에는 올리지 말아야 할 것이 있습니다. 대표적으로 4.6에서 본 비밀값 파일 .env(키가 새면 큰일!), 그리고 용량만 크고 다시 만들 수 있는 .venv 폴더입니다. 이런 것들을 .gitignore 파일에 적어두면 Git이 무시합니다.
# .gitignore (프로젝트 폴더 안) .env .venv/ __pycache__/
콜아웃 · 입문자가 가장 후회하는 실수.env(API 키가 든 파일)를.gitignore에 넣지 않고 GitHub에 올려, 키가 인터넷에 공개돼 버리는 사고가 정말 흔합니다. 한 번 올라간 키는 이력에 남아 지우기도 까다롭습니다. 새 저장소를 만들면 가장 먼저.gitignore에.env와.venv/를 적어두는 습관을 들이세요. RAG 프로젝트는 키를 쓰므로 특히 중요합니다.
지금은 Git을 깊이 쓸 필요는 없습니다. "변경을 세이브(커밋)하고, 필요하면 되돌리고, GitHub로 백업하며, 비밀·대용량 파일은 .gitignore로 제외한다" — 이 그림만 챙기면 Git 가이드 첫 줄에서 막히지 않습니다.
5.6 전체 흐름 한눈에
지금까지의 작업을 이어 붙이면, 거의 모든 Python 프로젝트의 시작 의식이 됩니다.
flowchart TB
A["① VS Code로<br/>프로젝트 폴더 열기"] --> B["② 내장 터미널 열기<br/>(cwd = 프로젝트 폴더)"]
B --> C["③ 가상환경 생성<br/>python -m venv .venv"]
C --> D["④ 활성화<br/>(.venv) 표시 확인"]
D --> E["⑤ 패키지 설치<br/>pip install -r requirements.txt"]
E --> F["⑥ 코드 실행<br/>python app.py"]
F --> G["결과 / 오류 확인"]
classDef step fill:#CDE7FF,stroke:#3B82C4,color:#000
classDef good fill:#D7F2C8,stroke:#5BA63B,color:#000
class A,B,C,D,E,F step
class G good
③ 가상환경 만들기는 프로젝트당 한 번. 그 뒤로는 ④ 활성화 → ⑤·⑥ 작업의 반복입니다.
직접 해보기
작은 프로젝트를 처음부터 끝까지 굴려봅니다.
- 폴더를 엽니다. VS Code에서 "파일 → 폴더 열기"로
rag-project(2부에서 만든 것)를 엽니다. 그런 다음 내장 터미널을 엽니다("터미널 → 새 터미널"). 프롬프트가rag-project안을 가리키는지pwd로 확인하세요. - 가상환경을 만듭니다.
python -m venv .venv(또는py -m venv .venv). 왼쪽 파일 목록에.venv폴더가 생기는지 보세요. - 활성화합니다.
.\.venv\Scripts\Activate.ps1(mac/Linux:source .venv/bin/activate). 프롬프트에(.venv)가 붙는지 확인하세요. 막히면 5.3 콜아웃을 보세요. - 패키지를 깝니다.
pip install requests후pip list로 목록에 보이는지 확인하세요. - 코드를 만들어 실행합니다. VS Code에서
app.py파일을 만들고 위 5.4의 예시 코드를 붙여넣은 뒤, 터미널에서python app.py를 실행하세요. 상태 코드가 출력되면 성공입니다. (인터넷이 막혀 있으면 오류가 날 수 있는데, 그 오류 메시지를 읽는 법이 바로 다음 챕터입니다.) - 끕니다.
deactivate로 가상환경에서 나옵니다.
- Git을 확인하고 무시 파일을 만듭니다.
git --version으로 설치를 확인하세요(없으면 5.5대로 설치). 그런 다음 VS Code에서 프로젝트 폴더에.gitignore파일을 만들고.env와.venv/를 적어두세요. 아직 커밋은 안 해도 됩니다 — 지금은 "비밀·대용량은 제외한다"는 습관만 만들어 둡니다.
여기까지 했다면, RAG 안내서가 "터미널에서 가상환경 켜고 패키지 깔고 실행하세요"라고 할 때 그대로 따라 할 수 있습니다.
이 챕터 한 줄 정리
VS Code로 폴더를 열고, PATH를 켜서 Python을 깔고, 프로젝트마다 가상환경(venv)을 만들어 활성화한 뒤((.venv) 확인!) pip로 패키지를 깔고 실행한다. Git으로 변경을 세이브·백업하되 .gitignore로 .env·.venv/는 제외한다 — 이게 모든 Python 프로젝트의 시작 의식이다.
마지막 챕터에서는, 이 모든 과정에서 반드시 만나게 될 오류를 두려워하지 않고 읽고 빠져나오는 법을 다룹니다.