파이썬 개발 환경 만들기: VS Code 설정과 venv 가상환경, pip 사용법 | 파이썬 강좌 2강

VS Code에 파이썬 확장을 설치하고 인터프리터를 선택하는 방법, venv로 가상환경을 만들고 활성화하는 방법을 단계별로 정리했어요. pip로 패키지를 설치·확인·삭제하고 requirements.txt로 목록을 관리하는 기본기까지 익힐 수 있어요.

이번 강에서는 코드를 편하게 작성하고 실행할 수 있도록 VS Code를 설정하고, 프로젝트마다 독립된 공간을 만드는 가상환경(venv)과 패키지 관리 도구 pip를 익혀요. 지난 강처럼 메모장과 터미널만으로도 파이썬을 실행할 수 있지만, 편집기와 가상환경을 갖춰 두면 오류를 미리 발견하고 프로젝트끼리 충돌하는 일을 막을 수 있어요.

왜 개발 환경을 갖춰야 할까요

파이썬 파일은 어떤 텍스트 편집기로든 만들 수 있어요. 하지만 코드 편집기를 쓰면 문법 강조, 자동 완성, 오류 표시, 버튼 한 번으로 실행하기 같은 기능을 쓸 수 있어서 학습 속도가 훨씬 빨라져요.

가상환경은 또 다른 문제를 해결해요. 프로젝트 A는 어떤 라이브러리의 1.0 버전이 필요하고 프로젝트 B는 2.0 버전이 필요하다면, 컴퓨터 전체에 하나만 설치해서는 둘 다 만족시킬 수 없어요.

가상환경은 프로젝트 폴더마다 별도의 설치 공간을 만들어 이런 충돌을 막아 줘요.

도구	역할
VS Code	코드를 작성하고 실행하는 편집기
파이썬 확장	VS Code에서 파이썬 자동 완성, 오류 표시, 실행 기능 제공
venv	프로젝트별 독립된 파이썬 환경을 만드는 내장 모듈
pip	외부 패키지를 설치·삭제하는 도구

VS Code 설치와 파이썬 확장

VS Code 설치하기

VS Code(Visual Studio Code)는 마이크로소프트가 만든 무료 코드 편집기예요. 공식 사이트(code.visualstudio.com)에서 운영체제에 맞는 설치 파일을 내려받아 설치하면 돼요.

Windows에서 설치할 때 'PATH에 추가' 항목과 '탐색기 메뉴에 Code로 열기' 항목을 체크해 두면 편리해요. 폴더에서 오른쪽 클릭으로 바로 VS Code를 열 수 있거든요.

파이썬 확장 설치하기

VS Code는 기본 상태에서 파이썬을 잘 알지 못해요. 왼쪽 막대의 확장(Extensions) 아이콘을 누르거나 Ctrl+Shift+X(macOS는 Cmd+Shift+X)를 누른 뒤 'Python'을 검색하세요.

게시자가 Microsoft인 'Python' 확장을 설치하면 돼요. 이 확장을 설치하면 자동 완성과 오류 분석을 담당하는 Pylance, 디버거 등이 함께 설치돼요.

비슷한 이름의 다른 확장도 많으니 게시자를 꼭 확인하세요.

프로젝트 폴더 열기

VS Code는 '파일'보다 '폴더' 단위로 작업할 때 가장 잘 동작해요. 바탕화면 같은 곳에 python-study 폴더를 만들고, 메뉴에서 파일 → 폴더 열기로 그 폴더를 여세요.

처음 폴더를 열면 '이 폴더의 작성자를 신뢰하나요?'라는 창이 뜰 수 있어요. 직접 만든 폴더라면 신뢰를 선택하면 돼요.

첫 파일 만들고 실행하기

탐색기에서 새 파일 아이콘을 눌러 hello.py를 만들고 다음 코드를 입력하세요. 확장자가 .py여야 VS Code가 파이썬 파일로 인식해요.

# hello.py
# VS Code에서 만든 첫 파이썬 파일
print("VS Code에서 실행한 첫 파일이에요!")
print("가상환경 준비 완료!")

편집기 오른쪽 위의 ▷(Run Python File) 버튼을 누르면 아래쪽 터미널 창에 결과가 나와요.

VS Code에서 실행한 첫 파일이에요!
가상환경 준비 완료!

버튼을 누르면 VS Code가 내부적으로 python hello.py 같은 명령을 터미널에 대신 입력해 줘요. 지난 강에서 직접 터미널에 입력했던 것과 같은 동작이에요.

통합 터미널 열기

VS Code 안에서도 터미널을 쓸 수 있어요. 메뉴의 터미널 → 새 터미널을 누르거나 단축키 Ctrl+`(백틱)을 누르면 돼요.

통합 터미널은 현재 연 폴더에서 시작하기 때문에 경로를 이동할 필요가 거의 없어요. 앞으로 나오는 명령은 모두 이 터미널에 입력한다고 생각하면 돼요.

인터프리터 선택하기

인터프리터는 파이썬 코드를 읽고 실행하는 프로그램, 즉 설치한 python 실행 파일이에요. 컴퓨터에 파이썬이 여러 개 설치되어 있거나 가상환경을 만들었다면, VS Code가 어떤 것을 쓸지 정해 줘야 해요.

선택 방법

1. Ctrl+Shift+P(macOS는 Cmd+Shift+P)로 명령 팔레트를 열어요.
2. Python: Select Interpreter를 입력해 선택해요.
3. 목록에서 사용할 파이썬을 골라요.

선택한 인터프리터의 버전은 파이썬 파일을 열었을 때 화면 오른쪽 아래 상태 표시줄에 나타나요. 그 부분을 클릭해도 같은 선택 창이 열려요.

지금 어떤 파이썬이 실행되는지 확인하기

다음 코드는 현재 실행 중인 파이썬의 위치와 버전을 보여 줘요. 맨 위의 import sys는 파이썬에 내장된 기능 묶음을 불러오는 문장인데, 자세한 내용은 나중에 배워요.

지금은 그대로 따라 입력하면 돼요.

# which_python.py
import sys  # 파이썬 내장 기능 묶음 불러오기 (나중에 배워요)

print("실행 파일 위치:", sys.executable)
print("파이썬 메이저 버전:", sys.version_info.major)

실행 결과는 컴퓨터마다 다르지만, 예를 들면 다음과 같아요.

실행 파일 위치: C:\Users\user\AppData\Local\Programs\Python\Python313\python.exe
파이썬 메이저 버전: 3

sys.executable은 지금 이 코드를 실행하는 파이썬 실행 파일의 경로예요. 가상환경을 선택한 뒤 다시 실행하면 이 경로가 프로젝트 폴더 안쪽으로 바뀌는 것을 확인할 수 있어요.

venv로 가상환경 만들기

venv는 파이썬에 기본으로 들어 있는 가상환경 도구라서 따로 설치할 필요가 없어요. 프로젝트 폴더에서 통합 터미널을 열고 아래 명령을 입력하세요.

# Windows
python -m venv .venv

# macOS / Linux
python3 -m venv .venv

-m venv는 'venv 모듈을 실행하라'는 뜻이고, 마지막의 .venv는 만들 폴더 이름이에요. 이름은 자유지만 .venv가 가장 널리 쓰이는 관례이고, VS Code도 이 이름을 자동으로 잘 찾아 줘요.

명령이 끝나면 프로젝트 폴더 안에 .venv 폴더가 생겨요. 이 안에 파이썬 실행 파일의 복사본(또는 링크)과 패키지 설치 공간이 들어 있어요.

python-study/
├── .venv/
│   ├── Scripts/   (Windows) 또는 bin/ (macOS·Linux)
│   ├── Lib/       패키지가 설치되는 곳
│   └── pyvenv.cfg
├── hello.py
└── which_python.py

VS Code 명령으로 만들기

명령 팔레트에서 Python: Create Environment를 선택하고 Venv와 사용할 파이썬 버전을 고르면 같은 .venv 폴더가 만들어져요. 이 방법은 만든 가상환경을 인터프리터로 자동 선택해 준다는 장점이 있어요.

가상환경 활성화와 비활성화

가상환경을 만들기만 해서는 터미널이 여전히 원래 파이썬을 사용해요. '활성화'를 해야 그 터미널에서 python과 pip가 가상환경 안의 것을 가리키게 돼요.

운영체제·셸	활성화 명령
Windows PowerShell	.venv\Scripts\Activate.ps1
Windows 명령 프롬프트(cmd)	.venv\Scripts\activate.bat
macOS / Linux (bash, zsh)	source .venv/bin/activate

활성화에 성공하면 프롬프트 앞에 (.venv)가 붙어요.

(.venv) PS C:\Users\user\Desktop\python-study>

이 상태에서 앞의 which_python.py를 실행하면 실행 파일 위치가 가상환경 안쪽으로 바뀌어 있어요.

실행 파일 위치: C:\Users\user\Desktop\python-study\.venv\Scripts\python.exe
파이썬 메이저 버전: 3

가상환경에서 빠져나오려면 deactivate를 입력하면 돼요. 프롬프트 앞의 (.venv)가 사라지면 원래 파이썬으로 돌아온 거예요.

deactivate

VS Code의 자동 활성화

인터프리터로 .venv를 선택해 두면, VS Code는 새 터미널을 열 때 가상환경을 자동으로 활성화해 줘요. ▷ 실행 버튼도 선택한 가상환경의 파이썬으로 코드를 실행해요.

자동 활성화가 안 된 것 같다면 터미널 창의 휴지통 아이콘으로 터미널을 닫고 새로 열어 보세요. 인터프리터를 바꾸기 전에 열어 둔 터미널에는 변경이 반영되지 않기 때문이에요.

pip 기본 사용법

pip는 PyPI(파이썬 패키지 저장소)에 올라온 외부 패키지를 설치하고 관리하는 도구예요. 가상환경을 활성화한 상태에서 사용하면 패키지가 그 프로젝트의 .venv 안에만 설치돼요.

자주 쓰는 명령

명령	하는 일
pip install 패키지	패키지 설치
pip install 패키지==버전	특정 버전 설치
pip install --upgrade 패키지	최신 버전으로 업그레이드
pip list	설치된 패키지 목록 보기
pip show 패키지	패키지 정보 보기
pip uninstall 패키지	패키지 삭제
pip freeze > requirements.txt	설치 목록을 파일로 저장
pip install -r requirements.txt	파일에 적힌 패키지를 한 번에 설치

패키지 설치해 보기

화면을 꾸며 출력해 주는 rich 패키지를 설치해 볼게요.

pip install rich

설치가 끝나면 pip list로 확인해요. 버전 숫자는 설치 시점에 따라 달라요.

Package            Version
------------------ -------
markdown-it-py     4.0.0
mdurl              0.1.2
pip                25.3
Pygments           2.19.2
rich               14.2.0

rich 하나만 설치했는데 다른 패키지도 함께 보여요. rich가 동작하는 데 필요한 패키지(의존성)를 pip가 자동으로 같이 설치했기 때문이에요.

설치한 패키지는 코드에서 바로 쓸 수 있어요.

# fancy.py
from rich import print  # rich의 print로 바꿔 쓰기 (불러오기 문법은 나중에 배워요)

print("[bold green]가상환경에 설치한 패키지로 출력해요![/bold green]")

가상환경에 설치한 패키지로 출력해요!

터미널에서는 이 글자가 굵은 초록색으로 표시돼요. 대괄호 안의 bold green은 rich가 해석하는 스타일 표시라서 화면에는 나오지 않아요.

python -m pip로 실행하기

pip 대신 python -m pip라고 쓰면 '지금 이 python에 연결된 pip'를 확실하게 사용할 수 있어요. 파이썬이 여러 개 설치된 컴퓨터에서 엉뚱한 곳에 설치되는 일을 막을 수 있어 많이 권장되는 방식이에요.

python -m pip install rich
python -m pip --version

python -m pip --version의 출력에는 pip가 연결된 경로가 함께 나와요. 그 경로에 .venv가 들어 있으면 가상환경에 제대로 설치되고 있는 거예요.

requirements.txt로 목록 관리하기

프로젝트를 다른 컴퓨터로 옮기거나 친구와 공유할 때 .venv 폴더를 통째로 복사하면 안 돼요. 가상환경 안에는 원래 컴퓨터의 경로가 기록되어 있어서 다른 곳에서는 제대로 동작하지 않아요.

대신 설치 목록만 파일로 남겨요.

pip freeze > requirements.txt

받는 쪽에서는 새 가상환경을 만들고 활성화한 다음 아래 명령 한 줄로 같은 패키지를 설치하면 돼요.

pip install -r requirements.txt

Git을 쓴다면 .gitignore에 .venv/를 적어서 가상환경 폴더가 저장소에 올라가지 않게 하세요.

자주 하는 실수와 오류

PowerShell에서 활성화가 막힐 때

Windows PowerShell에서 활성화하면 다음과 비슷한 오류가 날 수 있어요.

.venv\Scripts\Activate.ps1 파일을 로드할 수 없습니다.
이 시스템에서 스크립트를 실행할 수 없으므로 ...

PowerShell이 기본적으로 스크립트 실행을 막아 두었기 때문이에요. 현재 사용자에 한해 허용하려면 다음 명령을 한 번 실행한 뒤 다시 활성화하세요.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

ModuleNotFoundError가 날 때

패키지를 분명히 설치했는데 실행하면 이런 오류가 나올 때가 있어요.

ModuleNotFoundError: No module named 'rich'

대부분 '설치한 파이썬'과 '실행한 파이썬'이 서로 다를 때 생겨요. 다음 순서로 확인하세요.

• 터미널 프롬프트 앞에 (.venv)가 붙어 있는지 확인해요.
• VS Code 오른쪽 아래 인터프리터가 .venv로 선택되어 있는지 확인해요.
• python -m pip install 패키지로 실행 중인 파이썬에 다시 설치해요.

그 밖에 주의할 점

• macOS·Linux에서 python 명령이 없다고 나오면 python3를 사용하세요.
• 패키지 이름을 잘못 입력하면 ERROR: No matching distribution found 오류가 나요. 철자를 다시 확인하세요.
• 가상환경 폴더 안에 직접 내 코드 파일을 만들지 마세요. 코드는 프로젝트 폴더에, 가상환경은 .venv에 따로 두는 것이 원칙이에요.
• 프로젝트 폴더 이름이나 위치를 바꾸면 가상환경이 깨질 수 있어요. 그럴 때는 .venv를 지우고 다시 만든 뒤 requirements.txt로 재설치하면 돼요.

연습 문제

1. 새 폴더 practice를 VS Code로 열고, 그 안에 .venv라는 가상환경을 만든 뒤 활성화하세요. 그리고 인터프리터로 이 가상환경을 선택하세요.
2. check.py 파일을 만들어 '환경 점검을 시작해요'와 현재 파이썬의 메이저 버전을 출력하세요. 출력 형식은 파이썬 메이저 버전: 3처럼 만들어요.
3. 가상환경에 rich를 설치하고, 설치 목록을 requirements.txt로 저장한 뒤 rich를 삭제하는 명령을 차례대로 작성하세요.

정답 예시

1번

# Windows PowerShell
python -m venv .venv
.venv\Scripts\Activate.ps1

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate

활성화한 뒤에는 명령 팔레트에서 Python: Select Interpreter를 실행하고 .venv가 들어간 항목을 고르면 돼요.

2번

# check.py
import sys  # 파이썬 내장 기능 묶음 불러오기

print("환경 점검을 시작해요")
print("파이썬 메이저 버전:", sys.version_info.major)
print("점검 끝!")

환경 점검을 시작해요
파이썬 메이저 버전: 3
점검 끝!

print에 쉼표로 값을 여러 개 넘기면 사이에 공백 한 칸을 넣어 출력해요. 그래서 콜론 뒤에 공백이 하나 생겨요.

3번

pip install rich
pip freeze > requirements.txt
pip uninstall rich

pip uninstall을 실행하면 정말 삭제할지 묻는 Proceed (Y/n)?이 나오는데, y를 입력하면 삭제돼요. 이때 rich와 함께 설치되었던 의존성 패키지는 자동으로 지워지지 않는다는 점도 알아 두세요.

핵심 정리

• VS Code에는 게시자가 Microsoft인 'Python' 확장을 설치해요. 자동 완성, 오류 표시, 실행 버튼을 쓸 수 있어요.
• 작업은 폴더 단위로 열고, Python: Select Interpreter로 사용할 파이썬을 정해요.
• python -m venv .venv로 프로젝트마다 독립된 가상환경을 만들어요.
• 활성화는 Windows .venv\Scripts\Activate.ps1, macOS·Linux source .venv/bin/activate, 비활성화는 deactivate예요.
• pip로 패키지를 install, list, show, uninstall하고, python -m pip로 실행하면 설치 위치가 헷갈리지 않아요.
• 패키지 목록은 pip freeze > requirements.txt로 저장하고 pip install -r requirements.txt로 복원해요. .venv 폴더 자체는 공유하지 않아요.
• ModuleNotFoundError가 나면 실행 중인 인터프리터와 설치한 위치가 같은지 먼저 확인해요.

강좌 이어 보기

• 이전 강좌: 1강 파이썬이란? 설치하고 첫 프로그램 실행하기
• 다음 강좌: 3강 변수와 자료형 기초 (곧 올라옵니다)
• 파이썬 강좌 전체 목차 보기