Python 개발 환경 세팅 완벽 가이드 - uv로 초보 탈출 (4편)

Python 개발 환경 세팅 완벽 가이드 - uv로 초보 탈출 (4편)

정보 기준: 2026년 9월 / 메인 도구: Cline / 언어: Python

3편까지 Cline 설치와 모델 연결을 마쳤습니다. 이제 실제로 코딩할 Python 환경을 갖출 차례입니다. 기초 편의 마지막이에요.

"AI가 코드 짜주는데 환경 세팅까지 알아야 하나?" 싶을 수 있습니다. 하지만 환경이 엉키면 AI가 만든 코드도 실행이 안 됩니다. 원리를 알아야 문제가 생겼을 때 대처할 수 있고요. 다행히 이것도 Cline의 도움을 받아 쉽게 할 수 있습니다.

• 왜 가상환경이 필요한가
• Python 설치 (PATH 주의!)
• 2026년 대세 uv로 환경 만들기
• VS Code Python 확장 & 인터프리터 (초보 함정!)
• 첫 Python 코드 실행
• Cline으로 환경 세팅 자동화

 

왜 가상환경이 필요한가

먼저 개념부터입니다. 가상환경(virtual environment) 은 프로젝트마다 패키지를 따로 관리하는 격리 공간입니다.

가상환경 없이:
  모든 패키지가 한 곳에 섞임
  프로젝트A는 requests 2.28 필요
  프로젝트B는 requests 2.31 필요
  → 하나가 깨짐! 충돌!

가상환경 사용:
  프로젝트별로 격리된 공간
  A는 A 폴더에, B는 B 폴더에
  → 충돌 없이 깔끔!

가상환경은 "프로젝트 전용 서랍"이라고 생각하면 됩니다. AI 코딩에도 필수입니다. Cline도 이 환경 위에서 코드를 실행하니까요.

 

1단계: Python 설치

가장 기본인 Python 설치입니다.

1. 다운로드: python.org에서 최신 버전 (3.12 이상 추천)
2. 설치: "Add Python to PATH" 체크박스 꼭 체크!
3. 확인: 터미널에서 python --version

⚠️ PATH 체크 필수! 설치 화면에서 "Add Python to PATH" 체크박스를 꼭 체크하세요. 이걸 안 하면 터미널에서 python 명령을 인식하지 못합니다. 초보자가 가장 많이 놓치는 부분입니다.

막히면 Cline에게 물어보세요. "Python이 설치됐는지 확인해줘"라고 하면 Cline이 직접 확인하고 안내합니다. 2편에서 배운 그 에이전트 기능입니다.

 

2단계: uv로 환경 만들기 (2026년 대세)

가상환경을 만드는 방법은 여러 가지지만, 2026년에는 uv가 대세입니다.

전통 방법: venv (Python 내장)

python -m venv .venv
source .venv/bin/activate   # (Windows: .venv\Scripts\activate)

Python에 기본 내장되어 있어 무난합니다.

신무기: uv (추천)

uv init      # 프로젝트 초기화
uv venv      # 가상환경 생성

uv는 Rust로 만들어져 pip보다 10~100배 빠릅니다. Python 버전 관리까지 해줍니다.

더 좋은 소식: VS Code Python 확장이 uv를 자동으로 사용합니다(alwaysUseUv 기본 ON). 클릭 한 번으로 환경을 만들 수 있습니다.

초보 추천: 그냥 시작은 venv도 괜찮습니다. 하지만 새로 배운다면 미래인 uv를 추천합니다. 이 글은 uv 기준으로 진행합니다.

 

3단계: VS Code Python 확장 & 인터프리터

여기가 초보 함정 구간입니다. 집중해서 보세요.

1. Python 확장 설치

확장(Ctrl+Shift+X)에서 "Python" (Microsoft) 설치

2. 인터프리터 선택

Ctrl+Shift+P → "Python: Select Interpreter"

⚠️ 초보 90%가 겪는 에러! 가상환경을 잘 만들었는데도 ModuleNotFoundError가 뜬다면? VS Code가 전역 Python을 쓰고 있어서입니다. 가상환경(.venv)이 아니라요.

해결: Python: Select Interpreter에서 .venv/bin/python(프로젝트 환경)을 꼭 선택하세요. 이거 하나로 대부분의 import 에러가 해결됩니다.

uv로 환경을 만들면 VS Code가 대부분 자동으로 .venv를 감지하지만, 안 될 때는 위 방법으로 수동 선택하면 됩니다.

 

4단계: 첫 Python 코드 실행

환경이 잘 잡혔는지 간단한 코드로 확인합니다.

hello.py 파일을 만들고 입력합니다.

print("AI 코딩 시작! Hello, Cline!")

실행은 우측 상단의 ▶ 버튼 또는 F5를 누르면 됩니다. 터미널에 메시지가 나오면 성공입니다! 🎉

물론 Cline에게 "hello.py 만들어서 실행해줘"라고 하면 이것도 자동으로 해줍니다.

 

Cline으로 환경 세팅 자동화

사실 지금까지의 과정 대부분을 Cline이 대신 해줄 수 있습니다.

Cline에게 이렇게 말해보세요.

"Python 가상환경 만들고 requests 패키지 설치해줘"

그러면 Cline이 알아서 처리합니다.

1. Plan 모드로 "이렇게 할게요" 계획 제시
2. 승인하면 → 명령 실행 → 환경 완성 (매 단계 승인)

 

단, 원리를 알아야 문제가 생겼을 때 대처할 수 있습니다. 그래서 이번 편에서 기초를 배운 겁니다. AI가 다 해주더라도, 무슨 일이 일어나는지 이해하고 있으면 에러가 나도 당황하지 않습니다.

 

자주 겪는 문제 정리

초보자가 자주 만나는 문제와 해결법입니다.

1. python 명령이 안 먹혀요
   → PATH 체크 안 함. 재설치 시 "Add to PATH" 체크

2. ModuleNotFoundError
   → 인터프리터가 .venv 아님. Select Interpreter로 .venv 선택

3. 패키지 설치가 느려요
   → pip 대신 uv 사용 (10~100배 빠름)

4. 어떤 Python 버전을 써요?
   → 3.12 이상 추천, uv가 버전 관리도 해줌

5. .venv 폴더를 git에 올려도 되나요?
   → 안 됨! .gitignore에 .venv 추가

 

마무리 - 기초 편 완성!

이번 편의 핵심입니다.

1. 가상환경은 필수 — 프로젝트별 패키지 격리
2. Python 설치 시 PATH 체크 — 초보 필수
3. uv가 2026년 대세 — pip보다 10~100배 빠름
4. 인터프리터를 .venv로 선택 — ModuleNotFoundError 해결
5. Cline으로 자동화 가능 — 단, 원리는 알아두기

이번 편으로 기초 편(1~4편)이 완성되었습니다. VS Code + Cline 설치, 모델 연결, Python 환경까지 모든 준비가 끝났습니다. 이제 진짜 AI 코딩을 시작할 수 있습니다.

 

다음 편부터는 핵심 기능 편입니다. 5편에서는 AI 자동완성(Copilot/Codeium 무료)을 세팅해서, 코드를 타이핑하는 순간부터 AI의 도움을 받는 방법을 다룹니다.

 

환경 세팅하다 막히는 부분이 있으면 댓글로 남겨주세요.