AI 프로젝트 첫걸음, Python 가상환경 제대로 쓰기

LLM 공부 시리즈에서 프롬프트부터 에이전트, 멀티모달까지 LLM의 개념과 사용법을 살펴봤습니다. 이번 AI 개발자 로드맵 시리즈에서는 한 걸음 더 들어가 AI 앱을 직접 만들고, 배포하고, 운영하는 데 필요한 내용을 단계별로 정리합니다.

첫 단계는 개발 기본기입니다. AI 개발에서 가장 많이 쓰는 언어는 Python이고, Python 프로젝트를 시작할 때 가장 먼저 익혀야 할 것이 가상환경과 패키지 관리입니다. 이번 글에서는 가상환경이 왜 필요한지, Windows에서 만들고 쓰는 방법, 패키지를 기록하고 다시 설치하는 방법을 정리해 보겠습니다.

 

1. 가상환경이 필요한 이유

Python 패키지는 기본적으로 PC 전체에 하나의 공간으로 설치됩니다. 프로젝트가 하나일 때는 문제가 없지만, 여러 프로젝트를 다루다 보면 다음과 같은 문제가 생깁니다.

• 버전 충돌: A 프로젝트는 어떤 라이브러리의 1버전이, B 프로젝트는 2버전이 필요한데 PC에는 하나만 설치할 수 있습니다.
• 재현 불가: 내 PC에서는 잘 되던 코드가 다른 PC나 서버에서는 패키지 버전이 달라 동작하지 않습니다.
• 정리 어려움: 어떤 패키지가 어느 프로젝트 때문에 설치됐는지 알 수 없게 됩니다.

가상환경(virtual environment)은 프로젝트마다 독립된 Python 실행 환경과 패키지 설치 공간을 만들어 이 문제를 해결합니다. AI 라이브러리는 업데이트가 잦고 서로 의존하는 버전이 까다로운 편이라 가상환경은 사실상 필수입니다.

 

2. venv로 가상환경 만들기 (Windows)

Python에는 venv라는 가상환경 도구가 기본으로 들어 있습니다. 프로젝트 폴더에서 PowerShell을 열고 다음 순서로 진행하세요.

# 1) 프로젝트 폴더 만들고 이동
mkdir my-ai-app
cd my-ai-app

# 2) 가상환경 만들기 (.venv 폴더가 생김)
python -m venv .venv

# 3) 가상환경 켜기
.\.venv\Scripts\Activate.ps1

# 4) 켜졌는지 확인: 프롬프트 앞에 (.venv)가 붙고, 아래 경로가 .venv 안을 가리킴
python -c "import sys; print(sys.prefix)"

# 5) 작업이 끝나면 끄기
deactivate

PowerShell에서 "스크립트를 실행할 수 없습니다"라는 오류가 나면, 현재 사용자에 한해 로컬 스크립트 실행을 허용하는 다음 명령을 한 번 실행한 뒤 다시 켜 보세요.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

macOS나 Linux에서는 3번 명령만 source .venv/bin/activate로 바뀌고 나머지는 같습니다. VS Code 같은 편집기는 프로젝트 폴더의 .venv를 자동으로 인식해서 해당 Python을 사용하도록 설정할 수 있습니다.

 

3. pip로 패키지 설치하고 기록하기

가상환경을 켠 상태에서 pip로 설치한 패키지는 그 가상환경 안에만 설치됩니다.

명령어	설명
pip install 패키지	패키지 설치
pip install "패키지==1.2.3"	특정 버전으로 설치
pip list	설치된 패키지 목록 보기
pip freeze > requirements.txt	현재 설치된 패키지와 버전을 파일로 저장
pip install -r requirements.txt	파일에 적힌 패키지를 한 번에 설치
pip uninstall 패키지	패키지 삭제

requirements.txt는 "이 프로젝트를 실행하려면 이 패키지들이 필요하다"는 목록입니다. 다른 PC나 서버에서 가상환경을 새로 만든 뒤 pip install -r requirements.txt 한 줄이면 같은 환경을 다시 만들 수 있습니다.

제 PC(Windows 11, Python 3.14)에서 가상환경을 만들고 패키지를 설치한 뒤 requirements.txt로 기록해 본 화면입니다. 가상환경을 켜면 프롬프트 앞에 (.venv)가 붙고, sys.prefix가 프로젝트 안의 .venv 폴더를 가리키는 것을 확인할 수 있습니다.

 

프로젝트를 Git으로 관리한다면 .venv 폴더는 올리지 말고 requirements.txt만 올리세요. .gitignore 파일에 다음 줄을 넣으면 됩니다. API 키를 담는 .env 파일도 함께 제외하는 것이 좋습니다(3편에서 자세히 다룹니다).

# .gitignore
.venv/
.env
__pycache__/

 

4. 더 편한 도구: uv와 pyproject.toml

최근에는 uv라는 도구도 많이 쓰입니다. uv는 Rust로 만든 오픈소스 Python 패키지·프로젝트 관리 도구로, pip보다 설치 속도가 빠르고 가상환경 생성, 패키지 설치, Python 버전 설치까지 한 도구로 처리합니다.

# 새 프로젝트 만들기 (pyproject.toml 생성)
uv init my-ai-app
cd my-ai-app

# 패키지 추가 (가상환경이 없으면 자동으로 만들고, 버전 고정 파일 uv.lock도 갱신)
uv add 패키지

# 가상환경 안에서 스크립트 실행
uv run main.py

uv는 패키지 목록을 pyproject.toml에 기록합니다. pyproject.toml은 Python 프로젝트의 이름, 버전, 필요한 패키지 등을 적는 표준 설정 파일로, requirements.txt보다 더 많은 정보를 체계적으로 담을 수 있습니다.

구분	venv + pip	uv
설치	Python에 기본 포함	별도 설치 필요
속도	보통	빠름
패키지 기록	requirements.txt (직접 관리)	pyproject.toml + uv.lock (자동 관리)
추천 대상	처음 배우는 단계, 기본 도구만 쓰고 싶을 때	프로젝트가 많고 관리를 자동화하고 싶을 때

처음에는 venv와 pip로 원리를 익히고, 익숙해지면 uv로 넘어가는 순서를 추천합니다. 어떤 도구를 쓰든 "프로젝트마다 가상환경, 패키지 목록은 파일로 기록"이라는 원칙은 같습니다.

 

정리

가상환경은 프로젝트마다 독립된 패키지 설치 공간을 만들어 버전 충돌과 재현 문제를 막아 줍니다. Python 기본 도구인 venv로 가상환경을 만들고, pip로 설치한 패키지는 requirements.txt로 기록해 두세요. 프로젝트가 늘어나면 설치와 관리를 한 번에 해 주는 uv와 pyproject.toml도 좋은 선택입니다. 다음 글에서는 AI 라이브러리 코드를 읽고 쓸 때 꼭 만나게 되는 타입 힌트와 비동기(async) 문법을 알아보겠습니다.

 

참고자료

• Python 공식 문서, venv: https://docs.python.org/3/library/venv.html
• Python Packaging User Guide, Installing Packages: https://packaging.python.org/en/latest/tutorials/installing-packages/
• pip User Guide: https://pip.pypa.io/en/stable/user_guide/
• uv 공식 문서: https://docs.astral.sh/uv/