whoop-dataset

An open, community-contributed dataset of WHOOP data. People export their own WHOOP data and add it here through a pull request, so researchers, tinkerers, and app developers have real, multi-device WHOOP metrics to work with.

Caution

Never add your journal_entries.csv. The journal contains free-text behaviour logs (alcohol, caffeine, medications, illness, mental-health notes, and more) — it is the one export file that can hold genuinely sensitive personal information. It is not wanted here and PRs that include it are automatically rejected. See What to exclude.

This is a wellness dataset, not a medical one. WHOOP metrics are consumer wellness estimates; treat them as such. Nothing here is medical advice or diagnostic data.

---

What a WHOOP export looks like

You get your data from the WHOOP app: Menu → App Settings → Data Export → Download my data (WHOOP emails you a ZIP). A typical export contains these CSV files (exact names can vary slightly by export version):

File	Contents	Add it?
physiological_cycles.csv	Per-day cycle: recovery %, RHR, HRV, skin temp, SpO₂, day strain, energy, sleep summary	✅ yes
sleeps.csv	Per-sleep: onset/wake, stages (light/deep/REM/awake), efficiency, need, debt, respiratory rate	✅ yes
workouts.csv	Per-workout: activity, strain, HR zones, energy, distance, altitude	✅ yes
journal_entries.csv	Free-text behaviour/journal answers	🚫 never — see caution above

So a valid contribution is the three green CSVs — nothing else.

What this dataset is (and isn't)

• Is: per-day / per-night / per-workout aggregate metrics across many people and WHOOP generations. Great for cross-person recovery/sleep/strain analysis, model building, and app testing.
• Isn't: raw beat-to-beat R‑R intervals or raw sensor samples. WHOOP's export is aggregate; if you need signal-level data, this isn't the source.

How it's organised: device, then contributor

The dataset is sorted by WHOOP device, then by contributor:

contributions/<device>/<name>/

• <device> is the WHOOP generation the data came from: 3.0, 4.0, 5.0, or mg.
• <name> is either a username (e.g. alex) or an anonymous id (e.g. user-0001) — your choice.

If your data spans more than one WHOOP model, add a folder under each device with that device's data.

Anonymous or named — your choice

You decide how you appear:

• Anonymous: use an id like user-0001 as your folder name and set anonymized: true.
• Named: use your username as the folder name and set anonymized: false.

Either way: never include an email address, a journal file, or other personal data in the files. The three metric CSVs don't carry your name; you're responsible for confirming nothing identifying is left. CI double-checks — it fails on an email address or a journal file.

How to contribute — two ways

Easiest: open an issue (no git needed) ⭐

1. Export your WHOOP data (WHOOP app → App Settings → Data Export → Download my data).
2. Put only physiological_cycles.csv, sleeps.csv, and workouts.csv into a .zip — not the journal, no screenshots.
3. Open New issue → "Add my WHOOP data", fill the short form (device, date range, name-or-anonymous, consent), and drag your ZIP into the attachment box.

That's it — the maintainer validates and adds it. (GitHub accepts .zip attachments on issues; it won't accept a raw .csv, which is why you zip them.)

Advanced: open a pull request

Prefer git? Add contributions/<device>/<name>/ with the three CSVs + metadata.yml (copy the template, set device to match the folder) and open a PR. Full steps in CONTRIBUTING.md; the validator runs on every PR.

Repository layout

whoop-dataset/
├── README.md
├── CONTRIBUTING.md
├── LICENSE                      # dataset license (CC BY 4.0)
├── schema/
│   └── DATA_DICTIONARY.md       # what each CSV column means
├── scripts/
│   └── validate_contribution.py # structure + safety checks (stdlib only)
├── .github/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/validate.yml   # runs the validator on every PR
└── contributions/
    ├── _TEMPLATE/               # copy this folder to start
    │   ├── metadata.yml
    │   └── PLACE_YOUR_CSVS_HERE.md
    └── <device>/                # 3.0 | 4.0 | 5.0 | mg
        └── <name>/              # a username, or an anon id like user-0001
            ├── metadata.yml
            ├── physiological_cycles.csv
            ├── sleeps.csv
            └── workouts.csv

For example, the seed contribution lives at contributions/5.0/user-0001/.

License & consent

The dataset is published under CC BY 4.0 — free to use with attribution. By opening a PR you confirm the data is your own and that you consent to publishing it publicly. You can ask for your contribution to be removed at any time by opening an issue.

(Maintainer note: CC BY 4.0 is the default; open an issue if you think CC0 / public-domain would serve the dataset better.)

Disclaimer

Not affiliated with or endorsed by WHOOP. "WHOOP" is a trademark of its owner. This repository contains only data that individuals chose to export and share about themselves. Wellness estimates only — not medical data.