VS Code 파이썬 개발환경 설정 가이드: 설치부터 가상환경 venv 세팅까지

파이썬(Python)을 배우기로 결심했다면 가장 먼저 마주하는 난관이 있습니다. 바로 '개발환경 구축'인데요. 내 컴퓨터에 파이썬을 설치하고 코드를 작성할 편집기를 연결하는 과정이 초보자에게는 생각보다 낯설고 복잡하게 느껴질 수 있습니다. 그래서 이번 포스팅에서는 전 세계 개발자들이 가장 애용하는 무료 코드 편집기인 Visual Studio Code(VS Code)를 활용해, 누구나 막힘없이 파이썬 개발 환경을 만들 수 있도록 단계별로 차근차근 안내해 드리려 합니다. 탄탄한 환경 설정이 스트레스 없는 코딩의 첫걸음인 만큼, 이번 글을 보며 차근차근 따라 해 보세요!

Generated by Gemini AI.

📌 핵심 요약 3줄

• 파이썬 설치 시 Windows 사용자는 반드시 'Add Python to PATH' 옵션을 체크해야 합니다.
• VS Code 설치 후 'Python 확장 플러그인'을 추가해야 자동 완성, 디버깅 등의 강력한 기능을 쓸 수 있습니다.
• 프로젝트별 라이브러리 충돌을 막기 위해 가상환경(venv)을 활용하는 버릇을 들이는 것이 좋습니다.

---

1. 파이썬(Python) 설치 및 확인하기

개발 환경 구축의 시작은 파이썬 공식 홈페이지에서 설치 파일을 다운로드하는 것입니다. 운영체제별로 설치 과정에서 주의해야 할 핵심 포인트를 정리했습니다.

운영체제 (OS)	설치 시 필수 체크 및 주의사항	설치 확인 명령어 (터미널/cmd)
Windows	설치 첫 화면 하단의 [Add Python to PATH] 체크박스를 반드시 체크해야 명령어 인식이 됩니다.	python --version
macOS / Linux	기본적으로 구버전 파이썬이 내장된 경우가 많으므로, 공식 홈페이지에서 최신 3.x 버전을 받아 설치합니다.	python3 --version

명령 프롬프트(Windows)나 터미널(Mac)을 열고 위 표에 적힌 명령어를 입력했을 때 Python 3.X.X 형태로 버전 번호가 출력되면 성공적으로 설치된 것입니다.

---

2. VS Code 설치 및 파이썬 확장 기능 추가

코드를 더 편리하게 작성하기 위해 마이크로소프트에서 제공하는 무료 편집기인 Visual Studio Code(VS Code)를 세팅해 보겠습니다.

① VS Code 다운로드 및 설치

VS Code 공식 웹사이트에 접속해 본인의 OS에 맞는 설치 파일을 내려받습니다. 특별한 설정 변경 없이 기본값 그대로 '다음'을 눌러 설치를 완료하시면 됩니다.

② 파이썬 확장(Extension) 프로그램 설치

VS Code는 가볍고 강력하지만, 처음에는 파이썬 전용 도구가 포함되어 있지 않습니다. 아래 단계를 통해 날개를 달아주어야 합니다.

1. VS Code를 실행한 뒤, 왼쪽 사이드바 맨 아래에 있는 4개의 사각형 모양 아이콘(확장/Extensions)을 클릭합니다.
2. 검색창에 "Python"을 입력합니다.
3. Microsoft에서 제공하는 파이썬 확장 프로그램을 찾아 [Install] 버튼을 누릅니다. 이 확장이 설치되어야 코드 자동 완성, 문법 검사, 디버깅 기능을 제대로 쓸 수 있습니다.

---

3. 파이썬 개발환경 세팅 및 첫 실행

이제 편집기와 파이썬을 연결하고 첫 코드를 실행해 볼 차례입니다.

① 파이썬 인터프리터 지정

VS Code가 내 컴퓨터에 설치된 파이썬을 인식하도록 설정해야 합니다.

• VS Code 안에서 아무 파이썬 파일(.py)을 열거나 단축키 Ctrl + Shift + P (Mac은 Cmd + Shift + P)를 누릅니다.
• 검색창에 "Python: Select Interpreter"를 입력하고 선택합니다.
• 컴퓨터에 설치된 파이썬 버전 목록이 나오면, 방금 설치한 최신 버전을 클릭해 줍니다.

② 첫 번째 파이썬 코드 실행하기

1. 상단 메뉴에서 파일 -> 새 파일을 누르고 파일 이름을 hello.py로 저장합니다. (확장자 .py가 필수입니다.)
2. 편집창에 다음과 같이 입력합니다.
3. Python

    

   print("Hello, Python World!")
   

4. 코드를 실행하려면 상단 메뉴의 터미널 -> 새 터미널을 열고 아래 명령어를 입력합니다.
   • Windows: python hello.py
   • macOS: python3 hello.py
5. 터미널 창에 Hello, Python World!가 출력된다면 모든 환경 설정이 완벽하게 끝난 것입니다.

---

4. 개발 생산성을 높여주는 VS Code 핵심 기능

기능 명칭	단축키 및 사용법	활용 가치
코드 자동 완성	코드 작성 중 추천 목록 표시	오타를 줄이고 함수 이름을 빠르게 입력하도록 지원
코드 자동 형식화	Ctrl + Shift + I 또는 단축키 메뉴에서 Format Document 실행	삐뚤빼뚤한 들여쓰기와 공백을 공식 스타일에 맞춰 자동 정렬
통합 터미널	Ctrl + ~ (백틱 키)	별도의 cmd 창을 띄우지 않고 에디터 내부에서 즉시 코드 실행
디버깅 (Debugging)	코드 라인 왼쪽 클릭으로 중단점(Breakpoint) 설정 후 F5 입력	코드를 한 줄씩 실행하며 에러의 원인과 변수 값을 실시간 파시

---

5. 가상 환경(Virtual Environment) 구축하기 (선택 사항)

파이썬으로 여러 프로젝트를 진행하다 보면, A 프로젝트에서는 장고 4.0 버전이 필요한데 B 프로젝트에서는 장고 5.0 버전이 필요해서 라이브러리가 꼬이는 상황이 발생합니다. 이를 방지하기 위해 프로젝트마다 독립된 방을 만들어주는 '가상 환경' 기능이 필요합니다.

① 가상 환경 생성 및 관리 명령어 개요

작업 단계	실행 명령어	설명
가상 환경 생성	python -m venv myenv	현재 폴더에 myenv라는 이름의 독립된 파이썬 가상 공간을 만듭니다.
활성화 (Windows)	myenv\Scripts\activate	윈도우 환경에서 생성한 가상 환경을 깨우고 연결합니다.
활성화 (macOS)	source myenv/bin/activate	맥 환경에서 생성한 가상 환경을 깨우고 연결합니다.
가상 환경 종료	deactivate	작업이 끝나고 원래의 컴퓨터 기본 파이썬 환경으로 돌아옵니다.

가상 환경이 활성화되면 터미널 창 맨 앞에 (myenv)처럼 가상 환경 이름이 표시됩니다. 이 상태에서 설치하는 모든 라이브러리는 해당 프로젝트 방에만 깔끔하게 저장됩니다.

---

6. 개발을 위한 팁

• 가상 환경 폴더는 Git에 올리지 마세요: 협업을 하거나 깃허브(GitHub)에 코드를 올릴 때, 가상 환경 폴더(myenv)는 용량이 크고 환경 의존적이라 업로드하지 않는 것이 원칙입니다. 대신 내가 사용한 패키지 목록을 pip freeze > requirements.txt 명령어로 텍스트 파일에 기록해 코드와 함께 공유하세요.
• VS Code 테마와 폰트 커스텀: 개발 효율을 높이기 위해 눈이 편안한 테마(Drakula, One Dark Pro 등)를 적용하고, 가독성이 좋은 개발자용 D2Coding이나 JetBrains Mono 폰트를 적용해 보세요. 코드가 눈에 훨씬 잘 들어옵니다.

---

7. 흔히 하는 실수

• 경로(PATH) 설정 누락: 파이썬을 설치할 때 "Add Python to PATH"를 체크하지 않으면 터미널에 python을 입력했을 때 명령어를 찾을 수 없다는 에러가 뜹니다. 이 경우 당황하지 말고 파이썬 설치 프로그램을 다시 켜서 Modify(수정)를 누른 뒤 해당 옵션을 체크해 주면 해결됩니다.
• 스크립트 실행 시 파일 경로 불일치: 터미널에서 python hello.py를 실행할 때, 터미널이 가리키고 있는 폴더 위치와 실제 파일이 저장된 폴더 위치가 다르면 파일을 찾을 수 없다는 에러(No such file or directory)가 발생합니다. 항상 cd 폴더명 명령어를 통해 파일이 있는 위치로 이동한 뒤 실행해 주세요.

---

💡 맺음말

이번 포스팅에서는 파이썬 개발의 기본 베이스 캠프라고 할 수 있는 파이썬 설치와 VS Code 연동, 그리고 가상 환경 세팅까지 함께 알아보았습니다. 처음에는 단축키나 터미널 명령어가 조금 낯설 수 있지만, 몇 번 다뤄보면 금방 익숙해지실 거예요. 제대로 구축된 환경은 앞으로 여러분이 만들어갈 멋진 프로그램들의 든든한 밑거름이 될 것입니다.

개발 환경을 세팅하다가 막히는 부분이 있거나 에러 메시지가 뜬다면 혼자 고민하지 마시고 언제든 아래 댓글로 편하게 질문을 남겨주세요. 함께 해결해 나가겠습니다. 감사합니다!