25. 가상환경과 프로젝트 관리 - 프로처럼 세팅하기

가상환경과 프로젝트 관리

25. 가상환경과 프로젝트 관리 - 프로처럼 세팅하기

파이썬 프로젝트를 진지하게 시작하려면, 환경 관리부터 제대로 해야 한다. 가상환경(venv)과 pip, 프로젝트 구조를 익히면 어디서든 프로처럼 코딩할 수 있다.

---

가상환경이 필요한 이유

프로젝트 A는 requests 2.28 버전이 필요하고, 프로젝트 B는 requests 2.31이 필요하다면? 하나의 파이썬에 두 버전을 동시에 설치할 수 없다.

프로젝트 A → requests 2.28 필요
프로젝트 B → requests 2.31 필요
          → 충돌 발생! 😱

가상환경은 프로젝트마다 독립된 파이썬 환경을 만들어주는 도구다.

프로젝트 A (venv_a) → requests 2.28 ✓
프로젝트 B (venv_b) → requests 2.31 ✓
                    → 각자 독립! 😊

 

가상환경 워크플로우

---

venv로 가상환경 만들기

생성

# 프로젝트 폴더에서 가상환경 생성
python -m venv venv

venv라는 이름의 가상환경 폴더가 생긴다. 이름은 자유지만 관례적으로 venv 또는 .venv를 쓴다.

활성화

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

활성화되면 프롬프트 앞에 (venv)가 붙는다:

(venv) C:\my_project>

비활성화

deactivate

확인

# 어떤 파이썬을 쓰고 있는지 확인
(venv) $ python --version
Python 3.12.0

# 가상환경 안의 파이썬 경로 확인
(venv) $ which python       # macOS/Linux
(venv) $ where python       # Windows

---

pip - 패키지 관리

pip는 파이썬의 패키지 설치 도구다. 가상환경 안에서 사용하면 해당 환경에만 패키지가 설치된다.

패키지 설치

# 최신 버전 설치
pip install requests

# 특정 버전 설치
pip install requests==2.31.0

# 최소 버전 지정
pip install requests>=2.28.0

# 여러 패키지 한번에
pip install requests beautifulsoup4 pandas

패키지 확인

# 설치된 패키지 목록
pip list

# 특정 패키지 정보
pip show requests

출력 예:

Name: requests
Version: 2.31.0
Summary: Python HTTP for Humans.
Home-page: https://requests.readthedocs.io
...

패키지 삭제

pip uninstall requests

패키지 업그레이드

pip install --upgrade requests

---

requirements.txt - 의존성 관리

현재 환경을 파일로 저장

pip freeze > requirements.txt

생성된 requirements.txt:

beautifulsoup4==4.12.2
certifi==2023.7.22
charset-normalizer==3.3.2
requests==2.31.0
urllib3==2.1.0

파일로부터 한번에 설치

# 다른 컴퓨터에서, 또는 새 가상환경에서
pip install -r requirements.txt

이렇게 하면 어떤 환경에서든 동일한 패키지를 설치할 수 있다.

실전 워크플로우

# 1. 프로젝트 폴더 생성
mkdir my_project
cd my_project

# 2. 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

# 3. 필요한 패키지 설치
pip install requests pandas

# 4. requirements.txt 생성
pip freeze > requirements.txt

# 5. 코딩 시작!

---

프로젝트 폴더 구조

규모가 커지면 폴더 구조를 잡아두는 게 좋다.

간단한 프로젝트

my_project/
├── venv/               # 가상환경 (Git에 올리지 않음)
├── main.py             # 메인 실행 파일
├── utils.py            # 유틸리티 함수 모음
├── requirements.txt    # 의존성 목록
├── .gitignore          # Git 무시 파일
└── README.md           # 프로젝트 설명

중간 규모 프로젝트

my_project/
├── venv/
├── src/                # 소스 코드
│   ├── __init__.py
│   ├── main.py
│   ├── models.py
│   └── utils.py
├── tests/              # 테스트 코드
│   ├── __init__.py
│   └── test_utils.py
├── data/               # 데이터 파일
│   └── sample.csv
├── requirements.txt
├── .gitignore
└── README.md

__init__.py는 해당 폴더가 파이썬 패키지임을 알려주는 파일이다. 빈 파일이어도 된다.

---

.gitignore - Git에서 제외할 파일

가상환경 폴더나 캐시 파일은 Git에 올릴 필요가 없다. .gitignore 파일에 제외 규칙을 적는다.

파이썬 프로젝트용 .gitignore

# 가상환경
venv/
.venv/
env/

# 파이썬 캐시
__pycache__/
*.pyc
*.pyo

# IDE 설정
.vscode/
.idea/

# OS 파일
.DS_Store
Thumbs.db

# 환경 변수 (비밀키 등)
.env

# 배포 관련
dist/
build/
*.egg-info/

.gitignore 사용법

# 프로젝트 루트에 .gitignore 파일 생성 후 위 내용 작성
# Git은 이 파일에 적힌 패턴의 파일/폴더를 추적하지 않는다

핵심: venv/는 절대 Git에 올리지 않는다. 대신 requirements.txt로 환경을 재현한다.

---

실전 예시: 프로젝트 처음부터 세팅하기

# 1. 프로젝트 생성
mkdir weather_app
cd weather_app

# 2. 가상환경
python -m venv venv
source venv/bin/activate

# 3. 패키지 설치
pip install requests

# 4. 코드 작성

# main.py
import requests

def get_weather(city):
    """날씨 정보 조회 (예시)"""
    api_url = f"https://api.example.com/weather?city={city}"
    try:
        response = requests.get(api_url)
        data = response.json()
        return data
    except requests.RequestException as e:
        print(f"에러: {e}")
        return None

if __name__ == "__main__":
    city = input("도시 이름: ")
    weather = get_weather(city)
    if weather:
        print(f"날씨: {weather}")

# 5. 의존성 저장
pip freeze > requirements.txt

# 6. .gitignore 작성
# (위의 내용 참고)

# 7. Git 초기화
git init
git add .
git commit -m "Initial commit"

---

자주 하는 실수와 해결법

가상환경 활성화를 깜빡한 경우

# 패키지 설치했는데 import 에러가 난다면?
# → 가상환경이 활성화되지 않은 상태에서 설치한 것!

# 해결: 활성화 후 다시 설치
source venv/bin/activate
pip install requests

venv 폴더를 옮기거나 이름을 바꾸면?

# venv 폴더는 절대경로를 사용하므로 이동하면 깨진다
# → 삭제하고 다시 만든다

rm -rf venv                  # 삭제
python -m venv venv          # 다시 생성
source venv/bin/activate
pip install -r requirements.txt  # 패키지 복원

Windows에서 활성화 에러

# PowerShell 실행 정책 문제
# 해결: 관리자 권한으로 PowerShell 실행 후
Set-ExecutionPolicy RemoteSigned

---

직접 해보기

문제 1. 새 폴더를 만들고, 가상환경을 생성하고, 활성화한 뒤, requests 패키지를 설치해보자. pip list로 설치 결과를 확인하자.

문제 2. pip freeze > requirements.txt로 의존성 파일을 만들고, 가상환경을 삭제한 뒤, 새로 만든 가상환경에서 pip install -r requirements.txt로 복원해보자.

문제 3. 아래와 같은 프로젝트 폴더 구조를 만들어보자. (실제 파일 생성)

todo_app/
├── venv/
├── src/
│   ├── __init__.py
│   └── main.py
├── requirements.txt
└── .gitignore

문제 4. .gitignore 파일을 작성해서 가상환경, 파이썬 캐시, IDE 설정 폴더가 제외되도록 해보자.

정답 보기

# 문제 1 - 가상환경 생성 및 패키지 설치
# 터미널에서 실행:
#
# mkdir test_project
# cd test_project
# python -m venv venv
# source venv/bin/activate      (Windows: venv\Scripts\activate)
# pip install requests
# pip list
#
# 결과 예시:
# Package            Version
# requests           2.31.0
# certifi            2023.7.22
# ...
‍
‍
# 문제 2 - 의존성 파일로 복원
# 터미널에서 실행:
#
# pip freeze > requirements.txt
# deactivate
# rm -rf venv          (Windows: rmdir /s /q venv)
# python -m venv venv
# source venv/bin/activate
# pip install -r requirements.txt
# pip list              ← 이전과 동일!
‍
‍
# 문제 3 - 프로젝트 구조 만들기
# 터미널에서 실행:
#
# mkdir todo_app
# cd todo_app
# python -m venv venv
# mkdir src
# touch src/__init__.py      (Windows: type nul > src\__init__.py)
# touch src/main.py
# touch requirements.txt
# touch .gitignore
‍
# src/main.py 내용:
def main():
    print("Todo App 시작!")
‍
if __name__ == "__main__":
    main()
‍
‍
# 문제 4 - .gitignore 작성
# .gitignore 파일 내용:
#
# venv/
# .venv/
# __pycache__/
# *.pyc
# .vscode/
# .idea/
# .DS_Store
# .env

---

오늘의 정리

항목	내용
가상환경	프로젝트마다 독립된 파이썬 환경을 제공
venv 생성	python -m venv venv
활성화/비활성화	source venv/bin/activate / deactivate
pip install	패키지 설치. pip install 패키지명
requirements.txt	pip freeze로 생성, pip install -r로 복원
.gitignore	venv/, __pycache__/ 등 Git에서 제외할 파일 지정

---

다음 편 예고: 클래스와 객체 (1) - 나만의 자료형 만들기

지금까지 배운 리스트, 딕셔너리도 사실은 객체다. 나만의 자료형을 만들 수 있는 클래스의 세계로 들어가보자!

---

태그: 파이썬 Python 파이썬독학 가상환경 venv pip requirements 프로젝트관리 파이썬중급 IT교육