재현 가능한 연구를 위해 Python 실행 환경을 기록하는 방법
Python과 운영체제 버전, 의존성, 실행 명령과 예상 결과를 기록하고 새 가상 환경에서 분석을 검증합니다.
동료가 같은 분석을 실행하려면 무엇이 필요할까요?
실행 환경 기록에는 검증한 Python 버전, 운영체제, 외부 패키지와 버전, 실행 위치와 명령, 예상 결과가 필요합니다. 스크립트만 전달하면 동료는 무엇을 설치하고 어디에서 실행해야 하는지 추측해야 합니다. 이 장에서는 앞서 사용한 네 행의 모의 학습 시간 데이터를 다시 분석하며 환경을 기록합니다.
학습 시간 예제 프로젝트를 내려받아 빈 폴더에 압축을 풀고, 터미널에서 추출된 study-sessions/ 폴더로 이동하세요. 별도의 한국어 README 템플릿도 사용할 수 있습니다. 이 예제의 분석 코드는 Python 표준 라이브러리만 사용하므로 외부 패키지를 설치할 필요가 없습니다.
python --version
python analysis/analyze.py
Python 3의 명령이 python3인 시스템에서는 두 명령의 python을 모두 python3으로 바꾸세요. Windows에서 Python 런처가 설치되어 있다면 py -3도 사용할 수 있습니다. 실제로 분석에 사용한 인터프리터의 버전을 기록하는 것이 핵심입니다.
아래는 이 예제를 검증한 환경의 기록입니다. 자신의 연구에서는 실제로 확인한 값으로 바꾸세요.
운영체제: Linux x86_64
Python: 3.12.14
외부 의존성: 없음 (표준 라이브러리만 사용)
실행 위치: study-sessions/ 프로젝트 최상위 폴더
실행 명령: python analysis/analyze.py
예상 출력 파일: results/means.csv
새 가상 환경에서 실행해 보기
가상 환경(virtual environment)은 프로젝트별로 Python 패키지를 분리합니다. 이 예제는 추가 패키지가 없어도 실행되지만, 깨끗한 환경에서 다시 실행하는 과정을 연습하기에 적합합니다. 프로젝트 최상위 폴더에서 아래 명령으로 환경을 만드세요.
python -m venv .venv
생성할 때 사용한 Python이 가상 환경의 기반이 됩니다. 가상 환경을 만든다고 Python이 자동으로 원하는 버전으로 바뀌지는 않습니다. 아래에서는 운영체제에 맞는 명령 한 쌍만 실행하세요. 가상 환경의 인터프리터를 직접 지정하므로 별도로 활성화할 필요가 없습니다.
macOS 또는 Linux
.venv/bin/python --version
.venv/bin/python analysis/analyze.py
Windows PowerShell 또는 명령 프롬프트
.venv\Scripts\python.exe --version
.venv\Scripts\python.exe analysis\analyze.py
다른 연구에서 외부 패키지가 필요하다면 프로젝트의 잠금 파일(lockfile)이나 버전을 고정하고 재설치를 검증한 requirements.txt를 함께 보관하세요. 패키지 목록만으로 운영체제, 시스템 라이브러리나 하드웨어까지 기록되지는 않습니다. .venv/ 폴더 자체를 공유하는 대신 새 환경을 만드는 절차를 문서화하세요.
성공했는지 결과로 확인하기
정상 실행되면 터미널에 Wrote results/means.csv가 표시됩니다. results/means.csv를 열면 아래 표가 있어야 합니다. 조용한 환경은 (20 + 30) ÷ 2 = 25.0분, 배경 소음 환경은 (15 + 25) ÷ 2 = 20.0분입니다.
condition,mean_minutes
background-noise,20.0
quiet,25.0
프로젝트의 expected/means.csv 또는 예상 결과 표와 비교하세요. 다시 실행하면 생성된 표를 덮어쓰므로, 비교 기준인 예상 결과 파일은 따로 보관합니다. 이 모의 데이터는 계산 연습용이며 소음의 효과에 관한 연구 결론을 뒷받침하지 않습니다.
실제 분석이 부동소수점 라이브러리, GPU 또는 난수에 의존한다면 관련 설정과 시드, 허용할 수 있는 수치 오차도 기록하세요. 이 작은 예제의 정확한 일치 기준을 모든 연구에 그대로 적용할 필요는 없습니다.
README에 실행 기록을 남기고 다시 따라 해 보기
README에 자신의 Python 버전, 운영체제, 외부 의존성, 실행 명령과 예상 출력 경로를 적으세요. 앞 장의 Git 실습에서 기록한 코드 커밋 ID와 입력 데이터 버전도 함께 남기면 어떤 코드와 데이터로 실행했는지 추적할 수 있습니다.
별도의 빈 폴더에 예제를 다시 풀고, 방금 적은 안내만 보고 새 환경을 만들어 실행해 보세요. 기존 results/가 없는 상태에서 예상 표가 다시 생성되면 기본적인 인수인계 절차를 확인한 것입니다.
오류가 나면 무엇부터 확인할까요?
python명령을 찾지 못하면 Python 3 설치 여부와 실행 명령(python3또는py -3)을 확인하세요.venv생성이 실패하면 오류 메시지를 읽고 운영체제의 공식 Python 설치 안내에서 가상 환경 지원을 확인하세요.- 파일을 찾지 못하면
analysis/analyze.py와data/sessions.csv가 같은 프로젝트 아래에 있는지, 파일명에 추가 확장자가 붙지 않았는지 확인하세요. - 다른 프로젝트에서 import 오류가 나면 실제 사용하는 인터프리터와 해당 환경에 설치한 의존성을 확인하세요. 이 예제에는 외부 패키지가 필요하지 않습니다.
참고 자료
이 글은 The Turing Way Community가 CC BY 4.0로 공개한 내용을 참고·각색했습니다. Miss Formula는 학습 순서를 재구성하고 설명, 예제 및 연습 문제를 추가했습니다.