Python Vibe Coding Course — Part 4

Ensuring Reproducibility

Preserve your environment with requirements.txt

Illustration of a stack of blocks, a list of them, and the same stack rebuilt from the list

After Part 3, your analysis runs on your own PC. The next important step is to leave the environment in a form that third parties, such as co-authors, reviewers, or your future self, can reproduce. In Python, the standard approach is to export your libraries and their versions into a single text file called requirements.txt. This part explains how to create it and how others can use it to replicate your setup.

Dr. Hoo, if it runs on my PC, isn't that enough?
What matters is that co-authors, reviewers, and your future self can rebuild the same environment. The file for that is requirements.txt.
01

Why requirements.txt is necessary

What's written in requirements.txt?
Each library you used and its version, one per line. Whoever receives it can install the same versions with a single command.

As explained in Part 1, Python code runs only with the right combination of Python version and library versions. Code you wrote using pandas 2.2.0 may not work in someone else's environment that only has pandas 1.5.0.

requirements.txt is a text file that lists each library you used along with its version, one per line. Anyone who receives this file can install exactly the same versions of all the libraries with a single command.

Example contents of requirements.txt

pandas==2.2.0
openpyxl==3.1.2
matplotlib==3.8.2
numpy==1.26.3
seaborn==0.13.1

02

Generate requirements.txt

With your virtual environment active (the one you created in Part 2 as .venv), you will run one command in the terminal.

A quick reminder on activating the virtual environment

Open a terminal in VSCode from "Terminal → New Terminal" in the top menu. Then run the command for your system.

  • On Windows (PowerShell), run .venv\Scripts\Activate.ps1
  • On Windows (Command Prompt), run .venv\Scripts\activate.bat
  • On Mac / Linux, run source .venv/bin/activate

When (.venv) appears at the start of the prompt, the virtual environment is active.

With the virtual environment active, run the command below.

Terminal (run with (.venv) shown in the prompt)
pip freeze > requirements.txt

When the command completes successfully, a file named requirements.txt will appear at the root of your project folder. Open it and you will see all libraries currently installed in your virtual environment, each listed with its version.

Your folder structure at this point

my_first_analysis/
├── .venv/
├── data/
│   └── sample_data.xlsx
├── notebooks/
│   └── analysis.ipynb
├── results/
│   ├── scatter.png
│   └── statistics.csv
└── requirements.txt   # ← newly created

Whenever you install a new library as your analysis grows, you will need to update requirements.txt. Make a habit of running pip freeze > requirements.txt one more time at the very end.

03

Steps for a third party to reproduce your environment

To reproduce your analysis, a co-author or reviewer needs only the folder you hand over and the instructions inside it. Let's start by clarifying what to include.

Files and folders to share

Contents of the shared folder

my_first_analysis/
├── data/             # Raw data (shareable items only)
│   └── sample_data.xlsx
├── notebooks/
│   └── analysis.ipynb   # Analysis script
├── results/       # Output figures/tables (include for reference)
├── requirements.txt  # Created in Step 2
└── README.md      # Instructions (created in Step 4 below)

The .venv/ folder is not included. The recipient will regenerate it on their own PC.

Part 1 recap

The virtual environment (.venv) is the project's dedicated "work room" from Part 1. You don't need to ship the room itself. If you hand over requirements.txt, the list of tools the room contains, the recipient can build the same room on their own PC. That is why .venv stays out of the package.

You can share the folder however you like. You can zip it and send it by email, share it through cloud storage, or publish it on GitHub or Zenodo as covered in Part 5.

Steps for the recipient

The person who receives your folder first checks the Python version written in README.md, then verifies whether that version is installed on their PC.

  1. Open README.md and check the Python version (e.g., "Tested on Python 3.12")
  2. Check whether that version is installed. Run python --version in a terminal (on Windows with multiple versions installed, try py --list). If it is missing, download and install the required version from python.org/downloads.
  3. Open the folder in VSCode and run the commands below in the terminal.
Terminal (run inside the received folder)
# Windows (using Python 3.12) py -3.12 -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt # Mac / Linux (using Python 3.12) python3.12 -m venv .venv source .venv/bin/activate pip install -r requirements.txt

The first line creates a virtual environment with the version specified in README.md. Without the version number, the command uses the PC's default Python, which may behave differently. The final pip install -r requirements.txt installs all libraries at the exact versions listed.

The recipient can now reproduce the exact environment you ran analysis.ipynb in. Running the code will produce the same figures and statistics. That is reproducibility.

04

Write setup instructions in README.md

Be sure to include a README.md file in your folder. It is the first thing a third party will read, so it should look something like the example below.

README.md (example)
# Analysis Package for [Your Study Title] ## Setup ``` python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` ## Running the Analysis Open `analysis.ipynb` in VSCode and run the cells from top to bottom. Results will be saved to the `results/` folder. ## Python Version Tested on Python 3.12.

You can create and save README.md as a plain text file in VSCode or any text editor.

What is Markdown?

Symbols such as # and ``` in the example above follow a formatting convention called Markdown. By adding just a few simple symbols to plain text, you can create headings, code blocks, lists, and other formatting. Services like GitHub, Zenodo, Notion, and Slack all support Markdown, and README.md files are automatically rendered on GitHub.

For a full reference, see the supplementary article "Markdown Quick Reference". At minimum, just knowing # (headings) and ``` (code blocks) is enough.

05

Caveats on the way to complete reproducibility

Does that make everything exactly the same?
Not quite. The version of Python itself is not recorded. So write it in README.md, for example "Tested on Python 3.12."

requirements.txt is powerful, but there are a few things to keep in mind.

  • The Python version itself is not recorded. requirements.txt only tracks libraries, not the Python version. Be sure to write "Tested on Python 3.12" (or whatever version you used) explicitly in README.md.
  • OS-specific libraries. A few libraries work only on Windows or only on Mac. If the analysis needs to run on multiple operating systems, testing on each one is ideal.
  • Very long output. pip freeze exports every library in the environment, including the ones your libraries depend on, so the file can get long. If that bothers you, ask an LLM to help you trim it down to only the libraries you directly import.

That said, it is perfectly fine to start with the output of pip freeze as it is. Don't aim for perfection. For now, just make sure a requirements.txt exists.

06

Exclude .venv with .gitignore (optional)

When sharing your folder on GitHub, it is standard practice to exclude the .venv folder. It should be regenerated by the recipient, and it is also quite large. To exclude it, create a file named .gitignore at the root of your project folder with the contents below.

.gitignore
.venv/ __pycache__/ *.pyc .ipynb_checkpoints/

With this file in place, these files and folders will be automatically excluded when you upload to GitHub. Part 5 covers this in more detail.


✓

What you can now do

  • Export your environment with pip freeze > requirements.txt
  • Let others reproduce it with pip install -r requirements.txt
  • Write setup instructions in README.md
  • Exclude unnecessary files with .gitignore

In Part 5, the final part, we'll cover how to publish the folder you've built on Zenodo or GitHub. We'll also show how to add the link to your paper's Appendix, so that others can reproduce your research.

So when I add libraries, I export requirements.txt again.
Right. First, just get to the point where a requirements.txt exists.