如何记录 Python 环境以便复现研究

记录 Python、系统和依赖版本、运行命令与预期输出,附一份实际试跑过的环境记录。

语言简体中文

Python 环境需要记录哪些信息

发给同事一个脚本,他还需要知道用哪个解释器、要安装什么、从哪里执行命令。示例脚本只用 Python 标准库。记下你实际测试的 Python 版本、操作系统和运行命令。

python --version
python analysis/analyze.py

有些系统的 Python 3 命令叫 python3。Windows 上如果装了 Python 启动器,也可以用 py -3。

下面是学习时长示例的环境记录。分享自己的项目时,把这些信息换成实际测试过的版本和路径。

操作系统:Linux x86_64
Python:3.12.14
第三方依赖:无
从项目根目录运行:python analysis/analyze.py
预期生成:results/means.csv

需要时建一个隔离环境

虚拟环境可以让每个项目使用各自的 Python 包。这个例子没有第三方依赖,可以拿来练习如何在干净环境中运行。

python -m venv .venv

# macOS 或 Linux
.venv/bin/python analysis/analyze.py

# Windows
.venv\Scripts\python.exe analysis\analyze.py

项目用了第三方包时,用项目的锁文件或经过验证的固定版本依赖清单来记录。分享前按保存的步骤重建一次环境。如果还依赖某个操作系统或系统库,也要一并说明。

写清楚运行成功是什么样

尽量从一个新目录开始。把示例脚本放在 analysis/,把示例数据放在 data/。脚本会生成 results/means.csv,并打印它的相对路径。

condition,mean_minutes
background-noise,20.0
quiet,25.0

对照预期结果表检查输出。如果你的分析依赖不同平台上的浮点库,并且允许很小的数值差异,写明可接受的误差范围。

给这次运行做个记录

在 README 里写下终端显示的 Python 版本、操作系统、实际用的命令和输出路径,再用新建的环境试一遍。

运行失败时先检查哪里?

提示找不到文件时,确认脚本和 CSV 在指定目录里,并核对文件是否确实名为 sessions.csv。其他项目如果出现导入错误,先核对用的是哪个解释器,再检查是否装齐了依赖。

参考资源

本文参考并改编自 The Turing Way Community 以 CC BY 4.0 发布的章节。Miss Formula 重新组织了教学顺序,补充了讲解,并编写了贯穿示例和练习。