How to Document a Python Environment for Reproducible Research
Record Python, system and dependency versions, the analysis command and the expected output. Includes a worked environment record.
What to record about your Python environment
Sending a script is only part of the handoff. A colleague needs to know which interpreter it expects, what to install and how to start it. For this example, the script uses only Python’s standard library. Record the exact Python version you tested, your operating system and the run command.
python --version
python analysis/analyze.py
On systems where Python 3 is named python3, use that command. On Windows, py -3 is another option if the Python launcher is installed.
Here is the environment record for the study-session example. Use the versions from your own tested run when sharing a project.
System: Linux x86_64
Python: 3.12.14
Third-party dependencies: none
Run from the project folder: python analysis/analyze.py
Expected output: results/means.csv
Create an isolated environment when needed
A virtual environment gives your project its own Python packages. This example works without extra packages, so it is a manageable place to practice setting up a clean environment.
python -m venv .venv
# macOS or Linux
.venv/bin/python analysis/analyze.py
# Windows
.venv\Scripts\python.exe analysis\analyze.py
For a project with extra packages, record the dependencies and versions using the project’s lockfile or a tested pinned requirements file. Build the environment again from the saved instructions before sharing. A list of packages alone does not capture the operating system or system libraries.
Know what a successful run looks like
Run from a fresh working folder if you can. Save the example script in analysis/ and the example input in data/. The script creates results/means.csv and prints its relative path.
condition,mean_minutes
background-noise,20.0
quiet,25.0
Compare the output with the expected table. For analyses that depend on platform-specific floating-point libraries, document a tolerable numerical difference when exact equality is unnecessary.
Write a run note
Add the Python version reported by your terminal, your operating system, the command you ran and the output path to the README. Try the instructions in a fresh environment.
What to check if the run fails
For a file-not-found error, verify that the script and CSV are in the named folders and that the file is really named sessions.csv. For an import error in a different project, verify the interpreter and install its declared dependencies.
References
Adapted from a chapter by The Turing Way Community (CC BY 4.0). Miss Formula reorganized and expanded the explanations and wrote the worked example and exercises.