How to write a README for research code

The README is the first file anyone opens in a repository, and often the only one. A reviewer checking a paper, a student trying to reuse a method, or you in two years will all start there. If it is missing or vague, most of them stop.

Writing a good README for research code is not hard. It takes an hour, and it pays back that hour the first time someone else tries to run your analysis. This guide covers what sections to include, what to say in each, and ends with a short template you can copy.

What is a README for?

A README answers the questions a new reader has in the order they have them: what is this, can I run it, how, and how do I credit it. It is not a paper and not full documentation. It is a map.

For research code, the README also does a scientific job. It links the code to the paper it supports, says which data it needs, and tells the reader what result they should see if everything worked. That last part turns a repository from "here is some code" into something a reader can check.

Write it in Markdown and name it README.md. Hosting platforms such as GitHub and GitLab render it on the project front page, and archives such as Zenodo preserve it with the release.

Which sections does a research README need?

A research README needs about eight short sections. Not every project needs all of them, but leaving one out should be a decision, not an accident.

Section	Answers the question
Title and summary	What is this and which paper does it belong to?
Requirements and installation	What do I need, and how do I set it up?
Data	Where does the input come from, and where does it go?
How to run	Which commands, in which order?
Expected output	What should I see if it worked?
Project structure	Where is everything?
Citation	How do I credit this?
Licence and contact	What may I do with it, and who do I ask?

How should I open the README?

Open with a title and two or three sentences that say what the code does and why it exists. Then give the full reference or preprint link of the paper it supports.

Be specific. "Analysis code" says nothing. "Code to reproduce the survival analysis and Figures 2 to 4 in Smith et al. (2026)" tells the reader at once whether they are in the right place. If the code is a general tool rather than a single analysis, say what problem it solves and for whom.

A short status line also helps. Is this the code as submitted, as published, or still in development? Is it maintained? Honesty here saves readers from filing issues that will never be answered.

What goes into installation and requirements?

List the language version, the operating systems you tested on, and the exact steps to install dependencies. Assume the reader has a clean machine and none of your habits.

• Name the language and version, for example Python 3.11 or R 4.3.
• Point to the environment file: requirements.txt, environment.yml, renv.lock or a container definition.
• Give the install commands exactly as they should be typed.
• Mention anything outside the package manager: a compiler, a GPU, a licensed tool such as MATLAB, or a lot of memory.

Test these instructions on a machine other than yours before you publish. Missing install steps are the most common reason shared research code does not run. If dependencies are complicated, a container helps. We cover the options in reproducible environments.

How do I describe the data?

Say where every input comes from, how to get it, and where to put it. Data is usually the hardest part for a reader to reproduce, so this section deserves care.

For each dataset, give:

• its name and source, with a persistent identifier such as a DOI if one exists;
• how to obtain it: direct download, a script, or an access request for restricted data;
• the folder it should go in, matching the paths your code expects;
• its licence or terms of use, if they differ from the code.

If data cannot be shared, say so plainly and explain why. Then provide a small synthetic or sample dataset with the same structure, so readers can at least check that the pipeline runs. A restricted dataset with no sample leaves reviewers with nothing to test.

How do I explain running the code and the expected output?

Give the commands in the order they should be run, and then describe what success looks like. Expected output is the section most research READMEs leave out, and the one that makes the code checkable.

For running, numbered steps work best. If there is a single entry point, such as make all or python run_all.py, put it first. If steps take a long time, say roughly how long and on what hardware, so readers do not stop a job that is working.

For expected output, say which files appear and where, which figures and tables in the paper they correspond to, and what key numbers a reader should see. Include a tolerance if results can vary between runs or machines. A sentence such as "the main effect estimate in results/table2.csv should be 0.42, plus or minus 0.01" gives a reader a concrete check.

How should I handle citation and licence?

Tell readers exactly how to cite the code, and state the licence clearly. Without a licence, others cannot legally reuse your code, even if it is public.

For citation, give a DOI for the archived release and the preferred reference. Add a CITATION.cff file as well. The Citation File Format is a small, machine-readable file that GitHub, Zenodo and reference managers can read, and it keeps the citation in one place. Our post on citing software in papers explains why the code deserves its own citation.

For the licence, add a LICENSE file and name it in the README. choosealicense.com explains the common options in plain language, and our guide to choosing a licence for research code covers the decisions specific to research.

Is there a template I can copy?

Yes. Copy this, delete what you do not need, and fill in the rest. Keep each section short.

# Project title

Code to reproduce [analysis / figures] in:
Author A, Author B (2026). Paper title. Journal. https://doi.org/...

Status: code as published. Not actively maintained.

## Requirements
- Python 3.11 (tested on Ubuntu 22.04 and macOS 14)
- About 8 GB RAM; full run takes about 40 minutes

## Installation
    git clone https://example.org/group/project.git
    cd project
    python -m venv .venv && source .venv/bin/activate
    pip install -r requirements.txt

## Data
- Survey data: https://doi.org/... (CC BY 4.0). Download to data/raw/.
- Clinical records are restricted. A synthetic sample is in data/sample/.

## How to run
1. python src/01_clean.py
2. python src/02_model.py
3. python src/03_figures.py
Or run everything with: make all

## Expected output
- results/table2.csv: main estimate 0.42 (plus or minus 0.01)
- figures/fig2.pdf to fig4.pdf match Figures 2 to 4 in the paper

## Project structure
    data/      raw and processed data (not in Git)
    src/       analysis scripts
    tests/     automated tests
    results/   generated output

## Citation
Please cite the archived release: https://doi.org/...
See CITATION.cff.

## Licence
MIT for code. See LICENSE.

## Contact
Open an issue, or email the corresponding author.

What mistakes should I avoid?

Most weak READMEs fail in the same few ways. Check yours against this list before publishing:

• Written once, never updated. Paths and commands in the README no longer match the code.
• Assumes your machine. Absolute paths like /home/me/project or tools that "everyone has".
• No expected output. The reader runs the code and cannot tell if it worked.
• Too long. Methods detail belongs in the paper or separate docs. The README should be read in a few minutes.
• No licence. Public code without a licence is not open in any legal sense.

What should I do this week?

Open the repository for your most recent paper and compare its README with the template above. Add the missing sections, starting with expected output and citation. Then ask a colleague to follow the instructions on their own machine without your help, and fix every place they get stuck. That one test is worth more than any amount of polishing.