Windows에서 Python venv 만들기

프로젝트 폴더가 준비되었다면 그 안에서 코드를 실행할 Python 환경을 만든다. 이 장의 결과는 프로젝트 전용 .venv, 설치할 패키지 목록, 실제 실행 경로를 확인하는 점검 기록이다. API 접속과 데이터베이스 연결은 다음 장에서 진행한다.

예시의 C:\Users\minjun\auto-trading-lab은 가상 경로다. 자신의 프로젝트 위치로 바꾸고, PowerShell 명령은 그 폴더에서 실행한다.

내 환경에서 시작할 곳 찾기

Windows에서 Python 가상환경을 만들려면 사용할 Python 실행 파일을 정한 뒤, 프로젝트 폴더에 .venv를 만들고 그 실행 파일로 패키지를 설치한다. (.venv) 표시만으로 완료를 판단하지 않고 실제 경로를 확인한다.

• Python 설치 여부나 경로를 모른다면: 설치 상태 확인에서 사용할 실행 파일과 버전을 확인한다.
• Python은 있지만 .venv가 없다면: 가상환경 만들기에서 프로젝트 안의 .venv\Scripts\python.exe를 만든다.
• .venv는 있지만 패키지를 못 찾는다면: 실행 경로 점검으로 Python과 pip가 같은 환경을 가리키는지 확인한다.
• 실행 정책 때문에 활성화가 막힌다면: 활성화와 직접 실행에서 프로젝트 Python을 직접 지정하는 방법을 확인한다.

완료 후에는 외부 연결 없는 import 확인을 거쳐 한국투자증권 API 인증과 조회로 이동한다.

1. 설치 전에 현재 상태 확인하기

먼저 이미 설치된 Python과 편집기를 확인한다. 여러 Python을 구분하지 않고 설치를 반복하면 패키지를 넣은 환경과 프로그램을 실행하는 환경이 달라질 수 있다.

Get-Location
Get-Command python, py, code -ErrorAction SilentlyContinue
python --version
py --version

명령을 찾지 못했다는 결과는 해당 명령이 현재 터미널에서 보이지 않는다는 뜻이다. Python 자체가 없는 경우도 있고, 설치 직후라 터미널의 경로 정보가 갱신되지 않은 경우도 있다. 설치를 마쳤다면 PowerShell을 새로 열고 확인한다.

Codex에는 다음처럼 요청한다.

현재 auto-trading-lab 프로젝트의 Windows 실행 환경을 확인해줘.
Python 실행 파일의 위치와 버전, py 명령, VS Code 설치 여부를 조사해줘.
설치하거나 설정을 바꾸지 말고, 이미 있는 Python 중 이 프로젝트에서
사용할 후보와 확인하지 못한 항목을 구분해줘.

정상 결과는 버전 번호 하나가 아니라 어떤 실행 파일을 사용할지를 설명할 수 있는 상태다. VS Code는 파일을 읽기 위한 선택 도구이며 Python 실행에 필수는 아니다.

2. 지원 중인 Python 버전 정하기

Python 공식 문서는 버전의 상태를 기능 개발, 사전 공개, 버그 수정, 보안 수정 등으로 나눈다. 이 책에서는 Python LTS라는 별도 배포판을 가정하지 않는다. 2026년 10월 28일 확인한 지원표에서 3.14와 3.15는 버그 수정 단계다. 이 실습은 Python 3.14 계열을 기준으로 하되, 설치 시점의 패키지 호환성과 공식 지원 상태를 함께 확인한다. Python 공식 버전 지원표

설치는 Python 공식 Windows 안내를 따른다. Windows의 Python 설치 관리자와 기존 런처는 제공 명령이 다를 수 있으므로, 현재 설치 방식의 안내를 확인한다. 공식 다운로드 페이지에서 안정 버전을 선택하는 방법도 사용할 수 있다.

이 장에서는 기존 Python을 제거하거나 전역 기본값을 바꿀 필요가 없다. 3.14를 사용할 수 있는 환경이라면 다음처럼 명시적으로 확인한다.

py -3.14 --version
py -3.14 -c "import sys; print(sys.executable)"

3.14.x와 해당 Python의 경로가 표시되면 다음 단계로 간다. py를 사용할 수 없다면 설치된 python.exe의 전체 경로로 같은 명령을 실행한다. 예를 들어 확인한 경로가 C:\Python314\python.exe라면 PowerShell에서는 & 'C:\Python314\python.exe' --version처럼 호출한다. 이 경로는 형식 예시이며 자신의 PC에 같은 폴더가 있다고 가정하지 않는다. 지원이 끝난 버전이나 시험 버전을 우연히 선택한 상태에서는 패키지를 설치하기 전에 실행 파일부터 정한다.

3. 프로젝트 전용 가상환경 만들기

venv는 프로젝트마다 패키지를 따로 설치하는 표준 도구다. 코드와 설정은 프로젝트에 두고, 실행 파일과 설치 패키지는 .venv에 둔다. .venv는 다른 컴퓨터에 복사하기보다 설치 목록으로 다시 만든다. Python 공식 venv 설명

Set-Location 'C:\Users\minjun\auto-trading-lab'
py -3.14 -m venv .venv
Test-Path '.\.venv\Scripts\python.exe'

마지막 결과가 True이면 실행 파일이 생성된 것이다. 이미 .venv가 있다면 덮어 만들기 전에 그 환경의 버전과 설치 목록을 확인한다. 프로젝트 소스는 .venv 안에 작성하지 않는다.

이후 명령은 활성화 상태와 관계없이 프로젝트 Python을 직접 지정한다.

.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
.\.venv\Scripts\python.exe -m pip --version

예상 결과는 .venv\Scripts\python.exe 경로, 가상환경 여부 True, .venv 아래의 pip 설치 경로다. 이 세 가지가 일치하면 전역 Python과 구분할 수 있다.

Python과 pip의 실행 경로가 다를 때

pip install은 성공했는데 ModuleNotFoundError가 나오면, 패키지를 설치한 Python과 코드를 실행한 Python부터 비교한다. 프로젝트 루트에서 다음 세 줄을 실행한다.

Get-Location
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip --version

Python 경로가 현재 프로젝트의 .venv\Scripts\python.exe이고 pip 경로도 같은 .venv 안이면 환경이 일치한다. 실행 파일을 찾지 못하면 현재 폴더와 .venv 생성 여부를 먼저 확인한다. 이 두 경로가 확인되기 전에는 전역 Python에 패키지를 반복 설치하지 않는다.

py 명령이 실패해도 기존 .venv\Scripts\python.exe가 정상 실행된다면 그 경로로 계속 사용할 수 있다. 런처가 찾는 설치 목록과 프로젝트 가상환경의 실행 가능 여부는 따로 확인한다.

4. 활성화와 직접 실행 구분하기

매번 전체 경로를 입력하기 번거롭다면 현재 터미널에서 활성화할 수 있다.

.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"

터미널 앞에 (.venv)가 나타나더라도 출력된 실행 파일을 확인한다. 활성화는 현재 터미널이 Python을 찾는 순서를 바꾸는 편의 기능이다. 새 터미널이나 작업 스케줄러에는 그 상태가 자동으로 이어지지 않는다.

실행 정책 때문에 Activate.ps1이 차단되면 이 장의 직접 경로 명령으로 계속 진행할 수 있다. 활성화를 위해 컴퓨터 전체의 실행 정책을 바꿀 필요는 없다. 조직에서 관리하는 PC라면 현재 정책과 관리 규칙을 먼저 확인한다. PowerShell 실행 정책 설명

활성화한 터미널에서 원래 상태로 돌아갈 때는 deactivate를 실행한다. 프로젝트 작업이 끝나도 .venv 폴더 자체는 남아 있다.

5. 필요한 패키지와 설치 목록 준비하기

이 책은 HTTP 조회에 requests, 표 데이터 처리에 pandas, 설정 파일 읽기에 python-dotenv, MySQL 연결에 mysql-connector-python을 사용한다. 처음에는 이 네 가지로 시작한다. 실시간 웹소켓이나 차트 라이브러리는 해당 기능이 필요해질 때 추가한다.

프로젝트 루트의 requirements.in에 다음 내용을 저장한다. 이 파일은 직접 선택한 의존성 목록이다.

requests
pandas
python-dotenv
mysql-connector-python

프로젝트 가상환경에 설치한다. 기존 프로젝트에 검증된 requirements.txt가 있다면 새 목록을 만들기보다 그 파일을 우선 사용한다.

.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.in
.\.venv\Scripts\python.exe -m pip check

정상 결과는 의존성 충돌 없이 설치가 끝나는 것이다. pip check가 통과한 뒤 설치된 정확한 버전을 기록한다. PowerShell 5.1에서도 텍스트 인코딩이 명확하도록 다음처럼 저장한다.

.\.venv\Scripts\python.exe -m pip freeze | Set-Content -Encoding UTF8 requirements.txt
Get-Content -Encoding UTF8 requirements.txt

다른 컴퓨터에서는 같은 Python 계열로 .venv를 새로 만든 뒤 -m pip install -r requirements.txt로 설치한다. 운영체제와 Python 버전도 함께 기록해야 재현 범위를 이해할 수 있다. Python Packaging 공식 설치 안내

6. 외부 연결 없이 최소 실행 확인하기

패키지가 설치됐는지 확인하는 명령은 외부 API에 접속하지 않는다.

.\.venv\Scripts\python.exe -c "import requests, pandas, dotenv, mysql.connector; print('imports OK')"

imports OK가 출력되면 이번 장의 import 확인이 끝난다. 패키지 이름 python-dotenv와 Python에서 사용하는 모듈 이름 dotenv가 다른 점에 주의한다.

프로젝트에 이미 src의 Python 파일이 있다면 문법도 확인할 수 있다.

.\.venv\Scripts\python.exe -m compileall -q src

출력이 없고 종료 코드가 0이면 문법 검사에서 오류가 발견되지 않은 것이다. 이 검사는 API 인증, SQL 실행, 계산식의 정확성까지 증명하지 않는다. 각 단계의 실제 동작은 해당 장에서 별도로 확인한다.

Git을 사용한다면 .gitignore에 .venv/, config/.env, config/*token*, logs/를 포함한다. 공유할 결과 파일에 개인 정보가 없는지도 확인한다. 이 제외 목록은 나중에 만드는 파일의 비밀값 검토를 대신하지 않는다.

7. 오류를 실행 경로부터 좁히기

설치 오류를 해결하려고 TLS 검증을 끄거나 임의의 패키지 파일을 내려받지 않는다. 오류의 원인이 Python 버전, 네트워크, 패키지 호환성 중 어디에 있는지 나누어 확인한다.

8. 완료 기록 남기기

docs/environment-check.md에는 Python 버전, 실행 파일 경로, 패키지 설치 목록, pip check와 import 확인 결과를 적는다. 실제로 실행하지 않은 명령은 “미실행”으로 표시한다.

다음 네 가지가 맞으면 3장의 인증 준비로 넘어간다.

• 프로젝트 전용 .venv 실행 파일이 확인된다.
• 필요한 패키지를 같은 환경에서 import할 수 있다.
• requirements.txt에 설치 버전이 기록되어 있다.
• 비밀 설정과 .venv를 공유 대상에서 제외했다.

이 장의 명령은 환경 준비 예시다. 문서 자체가 독자의 컴퓨터에 Python이나 패키지를 설치하지 않으며, 설치 성공 여부는 자신의 실행 결과로 확인한다.