[파이썬] Python virtualenv + VS Code 권장 디렉토리 구조

 

🐍 Python virtualenv + VS Code 권장 디렉토리 구조 정리

Python 프로젝트를 진행하면서 가상환경(virtualenv or venv) 과 VS Code를 함께 사용할 경우, 프로젝트 구조를 어떻게 구성하는 것이 좋을까요?

프로젝트가 커지면 커질수록 관리, 유지보수, 테스트, 협업의 측면에서 일관된 디렉토리 구조는 매우 중요합니다. 이 글에서는 Python + VS Code 환경에서 권장되는 디렉토리 구조를 정리해봅니다.

---

✅ 전체 디렉토리 구조

my_project/
├── .venv/                  # Python 가상환경 (VS Code 자동 인식)
├── src/                    # 소스코드 디렉토리
│   └── my_package/         # 실제 패키지
│       ├── __init__.py
│       └── module1.py
├── tests/                  # 테스트 코드 디렉토리
│   └── test_module1.py
├── .vscode/                # VS Code 설정
│   └── settings.json
├── requirements.txt        # 패키지 목록
├── pyproject.toml          # 프로젝트 메타정보 (선택)
├── setup.py                # 패키징용 설정 (선택)
├── .gitignore              # Git 무시 파일
└── README.md               # 프로젝트 설명 파일

---

📌 각 디렉토리/파일 설명

항목	설명
.venv/	python -m venv .venv 로 생성한 가상환경. 프로젝트 루트에 위치시키면 VS Code가 자동으로 인식합니다. .gitignore에 추가해야 합니다.
src/	실제 소스코드가 위치하는 디렉토리입니다. 모듈 경로 충돌 방지를 위해 분리하는 것이 좋습니다.
tests/	pytest, unittest 등을 위한 테스트 파일을 보관합니다.
.vscode/settings.json	VS Code에서 Python 해석기, Linting, Formatting, Testing 등을 설정할 수 있습니다.
requirements.txt	설치해야 할 패키지 목록을 명시합니다.
setup.py, pyproject.toml	패키징 또는 의존성 관리 시 필요합니다. 단순 스크립트용 프로젝트라면 생략 가능합니다.
.gitignore	.venv/, __pycache__/, *.pyc 등을 무시하도록 설정합니다.
README.md	프로젝트 설명, 설치 방법, 사용법 등을 작성합니다.

---

🛠️ VS Code 설정 예시 (.vscode/settings.json)

{
  "python.pythonPath": ".venv/bin/python",             // Windows라면 ".venv\\Scripts\\python.exe"
  "python.envFile": "${workspaceFolder}/.env",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.analysis.extraPaths": ["./src"]
}

extraPaths 설정은 src/ 하위에 있는 패키지를 import할 수 있도록 도와줍니다. 예: from my_package import something

---

📦 가상환경 생성 및 설정

# 가상환경 생성
python -m venv .venv

# 가상환경 활성화
source .venv/bin/activate      # macOS/Linux
.venv\Scripts\activate         # Windows

# 패키지 설치
pip install -r requirements.txt

VS Code에서 인터프리터 설정

• Ctrl+Shift+P → “Python: Select Interpreter” → .venv 선택

---

🧪 테스트 코드 작성 예시 (tests/test_module1.py)

from my_package import module1

def test_add():
    assert module1.add(2, 3) == 5

# pytest 실행
pytest tests/

---

📝 .gitignore 예시

.venv/
__pycache__/
*.pyc
.vscode/

---

✅ 요약

• 가상환경은 .venv/로 프로젝트 루트에 위치

• 소스는 src/, 테스트는 tests/로 명확히 분리

• VS Code 설정은 .vscode/settings.json으로 커스터마이징

• requirements.txt로 패키지 버전 고정

• pytest, flake8, black 등을 설정하여 개발 생산성 향상

---

이러한 구조는 개인 프로젝트뿐만 아니라 협업 시에도 매우 유용합니다. 일관성 있고 관리하기 쉬운 Python 프로젝트를 만들고 싶다면, 이 구조를 기반으로 시작해보세요! 🚀