Python 개발 환경 구축 가이드 | Windows·Mac에서 venv 설정부터 pytest 실행까지 초보자용 설명

Python으로 테스트 자동화를 시작하려면 먼저 환경 구축이 필요합니다. “설치는 했는데 코드가 안 돌아가요”, “venv가 뭔가요?”라는 초보자의 막힘을 해소하기 위해, Windows·Mac 각각의 절차를 명령어 한 줄씩 차근차근 설명합니다.

📌 이 글의 대상 독자

📖 이 글을 읽으면 할 수 있는 것

필자는 여러 프로젝트에서 Python × Selenium·Playwright·pytest를 활용한 테스트 자동화를 실천하고 있습니다.
새로운 팀원에게 환경 구축을 가르칠 때마다 항상 막히는 포인트가 정해져 있다는 것을 알게 됐습니다.
이 글은 그 경험을 바탕으로 초보자가 실제로 막히기 쉬운 부분을 미리 짚어서 설명합니다.

환경 구축의 전체 흐름

① Python 설치

Windows의 경우

1. Python 공식 사이트에서 인스톨러 다운로드
브라우저에서 python.org/downloads에 접속해 Python 3.12.x 인스톨러를 다운로드합니다. 최신 버전은 일부 라이브러리가 아직 미대응인 경우가 있으므로, 한 마이너 버전 전의 안정판이 무난합니다.

2. 인스톨러 실행
다운로드한 .exe 파일을 실행합니다. 실행 직후 화면에서 반드시 다음을 확인하세요.

3. 설치 완료 후 명령 프롬프트 실행
시작 메뉴에서 “cmd”를 검색해 명령 프롬프트를 열거나, Windows + R → cmd → Enter를 누릅니다.

Mac의 경우

Mac에는 기본적으로 오래된 Python이 설치되어 있지만, 테스트 자동화에는 새 버전을 별도로 설치하는 것을 권장합니다.
Homebrew를 사용하는 방법이 가장 간단합니다. Homebrew 설치 자체가 어렵게 느껴지면 python.org/downloads의 공식 인스톨러를 사용해도 괜찮습니다.

1. Homebrew가 없다면 설치
터미널을 열고(Finder → 응용 프로그램 → 유틸리티 → 터미널) 다음을 실행합니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Homebrew로 Python 설치

brew install python

② 설치 확인

설치가 완료됐으면 커맨드 라인에서 버전을 확인합니다.

# 명령 프롬프트(Windows) 또는 터미널(Mac)에서 실행
python --version

정상 출력 예시:

Python 3.12.3

pip(라이브러리 관리 도구)도 확인합니다.

pip --version
# 또는
pip3 --version

정상 출력 예시:

pip 24.0 from /usr/local/lib/python3.12/site-packages/pip (python 3.12)

③ venv로 가상 환경 만들기 (중요)

venv(가상 환경)란?

venv란 프로젝트별로 독립된 Python 환경을 만드는 구조입니다.

예를 들어 다음과 같이 프로젝트마다 필요한 라이브러리 버전이 다른 경우에도, 가상 환경을 사용하면 서로 간섭 없이 관리할 수 있습니다.

가상 환경 없이 모든 프로젝트에 공통 Python을 사용하면 버전 충돌로 동작하지 않는 경우가 자주 발생합니다.

가상 환경 만드는 절차

1. 프로젝트 폴더를 만들고 이동

# 폴더 생성
mkdir my-test-project

# 폴더로 이동
cd my-test-project

2. 가상 환경 생성

python -m venv venv
# Mac에서 python3가 필요한 경우:
# python3 -m venv venv

venv 폴더가 생성됩니다. 이 시점의 폴더 구성은 다음과 같습니다.

my-test-project/
├── venv/              ← 가상 환경 (Git에는 포함하지 않음)
├── test_sample.py     ← 테스트 파일 (나중에 생성)
└── requirements.txt   ← 라이브러리 목록 (나중에 생성)

3. 가상 환경 활성화(activate)

# Windows(명령 프롬프트)
venv\Scripts\activate

# Windows(PowerShell)
venv\Scripts\Activate.ps1

# Mac / Linux
source venv/bin/activate

활성화되면 명령 프롬프트/터미널 앞에 (venv)가 표시됩니다.

(venv) C:\Users\yourname\my-test-project>   # Windows 예시
(venv) yourname@mac my-test-project %       # Mac 예시

(venv)가 표시되는 동안은 가상 환경이 활성화된 상태입니다.
작업을 시작하기 전에 매번 activate하는 습관을 들이세요.

4. 가상 환경 종료

deactivate

④ pip으로 라이브러리 설치

pip은 Python의 패키지 관리 도구입니다. 테스트 자동화에서 자주 쓰는 라이브러리를 설치해 봅니다.
반드시 가상 환경을 활성화(activate)한 상태에서 실행하세요.

먼저 pip 자체를 최신 버전으로 업데이트합니다(권장)

python -m pip install --upgrade pip

# pytest (테스트 프레임워크)
pip install pytest

# Selenium (브라우저 자동화)
pip install selenium

# Playwright (모던 브라우저 자동화)
pip install playwright
playwright install  # 브라우저 본체 설치

# requests (API 테스트)
pip install requests

설치된 라이브러리 목록을 확인하려면:

pip list

requirements.txt로 한 번에 관리

팀 개발이나 환경을 재현할 때 requirements.txt에 라이브러리를 기록해 두면 편리합니다.

# 현재 환경을 파일로 내보내기
pip freeze > requirements.txt

# 파일에서 한 번에 설치(환경 재현 시)
pip install -r requirements.txt

⑤ VS Code 설정

에디터는 무엇이든 상관없지만, Python 테스트 자동화에서는 VS Code(Visual Studio Code)가 널리 쓰입니다. 무료로 사용할 수 있고 Python 지원이 충실합니다.

설치와 추천 확장 기능

code.visualstudio.com에서 다운로드해 설치합니다.
설치 후 다음 확장 기능을 추가하는 것을 권장합니다(VS Code 왼쪽 확장 기능 아이콘에서 검색해 설치).

VS Code에 가상 환경 인식시키기

VS Code에서 프로젝트 폴더를 열고 오른쪽 하단의 Python 버전 표시를 클릭해 만든 가상 환경의 Python을 선택합니다.

# 또는 Ctrl+Shift+P(Mac: Cmd+Shift+P)로 커맨드 팔레트를 열고
# "Python: Select Interpreter" 선택
# → ./venv/Scripts/python.exe(Windows) 또는 ./venv/bin/python(Mac) 선택

⑥ 동작 확인

마지막으로 환경이 올바르게 갖춰졌는지 확인합니다.

pytest 동작 확인

프로젝트 폴더에 test_sample.py라는 파일을 만들고 다음을 붙여넣습니다.

# test_sample.py
def test_addition() -> None:
    assert 1 + 1 == 2

def test_string() -> None:
    assert "hello".upper() == "HELLO"

터미널(가상 환경이 활성화된 상태)에서 실행합니다.

# 일반적인 실행 방법
pytest test_sample.py -v

# pytest 명령어를 찾을 수 없는 경우
python -m pytest test_sample.py -v

정상 출력 예시:

========================= test session starts ==========================
collected 2 items

test_sample.py::test_addition PASSED                            [ 50%]
test_sample.py::test_string   PASSED                            [100%]

========================== 2 passed in 0.12s ==========================

“2 passed”가 표시되면 환경 구축 완료입니다. 🎉

실무에서 자주 막히는 포인트 7가지

자주 묻는 질문 (FAQ)

정리

환경 구축이 완료됐으면 다음 단계로 pytest 기본 사용법이나 Selenium 설정으로 넘어갑시다.
위의 관련 글에서 다음 단계를 선택해 보세요.

환경 구축은 한 번 제대로 해두면 이후에는 코드 작성에만 집중할 수 있습니다. 서두르지 말고 한 단계씩 진행하세요.