Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
Synthea is an open-source simulator from The MITRE Corporation that generates synthetic patient records, from birth to death, as FHIR, C-CDA, CSV and other files. This guide is for researchers and research-IT staff who need test patients for a pipeline, a teaching dataset or a software demonstration. After reading it you can install Synthea, run a reproducible population, switch export formats and read the CSV tables. It is not clinical or medical advice, and Synthea output is not real patient data.
Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.
What Synthea is used for in research
Synthea models synthetic patients and their health histories: conditions, medications, vaccinations, laboratory results, procedures and care plans. Its README describes the records as synthetic and realistic but not real, and the software is released under the Apache-2.0 licence (copyright 2017-2025 The MITRE Corporation). Demographics default to the Massachusetts census unless you choose another state, and disease logic is held in modular rules that can be extended with custom modules.
Because no real person is behind a record, typical uses are building and testing data pipelines, exercising FHIR or CSV importers, and preparing training material before access to real data is approved. Synthetic output should still be disclosed as synthetic in a methods section or data management plan; see Synthetic Data in Research for documentation and sharing practice, and the synthetic data definition. The sources read for this page do not establish how closely Synthea populations match real-world statistics, so this guide makes no claim about statistical fidelity.
How to install or access it
The official source is the synthetichealth organisation on GitHub: github.com/synthetichealth/synthea. Both routes need a Java Development Kit (JDK, not a JRE) version 17 or newer; the README recommends a long-term-support release (17 or 25).
- Jar route (basic setup): install JDK 17 or newer, then download
synthea-with-dependencies.jarfrom the project’s master-branch-latest release. - Source route (developer setup): run
git clone https://github.com/synthetichealth/synthea.git, thencd synthea, then./gradlew build check test. On Windows use.gradlew.bat build check test.
Run it: step by step
- Print the usage text. Jar:
java -jar synthea-with-dependencies.jar -h. Source:./run_synthea -h(Windows:.).
un_synthea.bat - Generate a default population. Jar:
java -jar synthea-with-dependencies.jar. Source:./run_synthea -p 1000sets the population size to 1,000. - Choose a place. Give a state, and optionally a city, as positional arguments after the options:
./run_synthea Massachusettsor./run_synthea -s 12345 -p 1000 Utah "Salt Lake City". Quote any argument that contains spaces. - Fix the seed for a reproducible run. With
-s, the same seed and the same Synthea version produce an identical population. Record both in your methods notes (see computational reproducibility). - Find the output. By default files go to an
outputfolder (theexporter.baseDirectorysetting, default./output/), with one subfolder per export type. Change it with, for example,--exporter.baseDirectory="./output_tx/".
Command-line options
| Option | Effect (per the official wiki) |
|---|---|
-s |
Random seed; same seed and same version give an identical population |
-r |
Reference date, format YYYYMMDD |
-cs |
Clinician seed |
-p |
Population size (living patients) |
-g |
Gender, for example F |
-a |
Age range, minAge-maxAge |
-c |
Load a local settings file |
-d |
Directory of modules |
-h |
Print usage |
--<setting>=value |
Override any configuration property; no spaces around the equals sign |
Defaults for every setting live in src/main/resources/synthea.properties; override them on the command line, with a local file via -c, or with the web-based guided customizer.
Output formats and how to read them
FHIR and C-CDA files are written to ./output by default according to the README, but the exporter switches differ. The table below uses the property keys named in the README and the MITRE tutorial.
| Format | Switch | Default |
|---|---|---|
| HL7 FHIR (R4, STU3, DSTU2) | exporter.fhir.export |
README: FHIR is written to ./output by default |
| FHIR US Core R4 profiles | --exporter.fhir.use_us_core_ig true |
Optional |
| Bulk FHIR (ndjson) | exporter.fhir.bulk_data = true |
Off |
| C-CDA | exporter.ccda.export = true |
Off |
| CSV | exporter.csv.export = true |
Off |
| CPCDS | exporter.cpcds.export = true |
Off |
For example, ./run_synthea -p 100 --exporter.csv.export=true adds CSV files in ./output/csv. FHIR output lands in ./output/fhir: each file is a Bundle in JSON for one patient and begins with a single Patient resource.
Reading the CSV files
The official CSV data dictionary lists these tables: patients, encounters, organizations, providers, payers, payer_transitions, allergies, careplans, conditions, medications, procedures, observations, immunizations, imaging_studies, devices, supplies, claims and claims_transactions. Clinical codes use standard systems:
| Table | Code system | Key columns named in the dictionary |
|---|---|---|
| patients | none (demographics) | Id, BirthDate, DeathDate, First, Last, Gender, Race, Ethnicity, Address, Healthcare_Expenses, Income |
| encounters | encounter code | Id, Start, Stop, Patient, Organization, Provider, Payer, EncounterClass, Code, Total_Claim_Cost |
| medications | RxNorm | linked to Patient and Encounter |
| observations | LOINC | Date, Patient, Encounter, Code, Value, Units, Type |
| immunizations | CVX | linked to Patient and Encounter |
To build an analysis table, join clinical tables to patients on the patient identifier and to encounters on the encounter identifier. The dictionary’s patients table includes an SSN column and name and address fields; these values are generated, not real. Treat the whole population as synthetic when you cite it.
Troubleshooting
- Install the JDK, not the JRE. The wiki says to select the JDK in the installer.
- Use JDK 17 or newer. The README sets 17 as the minimum and recommends an LTS release.
- Quote arguments with spaces, such as
"Salt Lake City". - No spaces around the equals sign in
--setting=valueoptions. - Expected CSV or C-CDA files are missing: those exporters are off by default; enable them with the switches above.
- More records than
-p:-psets living patients, and patients who die during the simulation are also exported, so totals can be higher. - Results differ between runs: set the same
-sseed and use the same Synthea version.
Free alternatives
Few free tools generate whole synthetic patient records the way Synthea does. The options below are what the vendors’ own pages describe; none was tested for this guide, and none is claimed to be better or more accurate than Synthea.
| Option | What its own documentation says | Official page (read 2026-11-08) |
|---|---|---|
| Synthea pre-generated sample data | Over a thousand sample patients as ZIP downloads in FHIR R4, STU3, DSTU2, C-CDA and CSV; described as realistic but not real. Use it when you do not need to run the generator yourself. | synthetichealth.github.io/synthea |
| SyntheticMass | An application, built on the same project, that gives API access to synthetic patient data at city, town and individual level; no download is mentioned on the page read. | synthetichealth.github.io/synthea |
| Synthetic Data Vault (SDV) | A different approach: it trains a synthesizer on your own real tabular data (single-table, sequential or multi-table) and generates new rows. It needs real source data, so it suits cases where Synthea’s modelled patients do not match your schema. The page describes Community and Enterprise tiers and does not name the library licence here, so check the terms before use. | docs.sdv.dev/sdv |
FAQ
Is Synthea output real patient data?
No. The README describes the output as synthetic, realistic but not real records. Describe it as synthetic in any publication or data deposit.
Is Synthea free to use?
The source code is published under the Apache-2.0 licence, copyright The MITRE Corporation.
Which Java version does it need?
A JDK 17 or newer; the README recommends a long-term-support version (17 or 25).
How do I get exactly the same population twice?
Run with the same -s seed and the same Synthea version.
Does Synthea export FHIR?
Yes: HL7 FHIR R4, STU3 and DSTU2, plus Bulk FHIR ndjson on request and US Core R4 profiles through --exporter.fhir.use_us_core_ig true.
Sources
- Synthea README, synthetichealth/synthea on GitHub (read 2026-11-08)
- Basic Setup and Running, Synthea wiki (read 2026-11-08)
- Developer Setup and Running, Synthea wiki (read 2026-11-08)
- CSV File Data Dictionary, Synthea wiki (read 2026-11-08)
- SDV documentation (read 2026-11-08)
- Running Synthea, MITRE FHIR for Research tutorial (read 2026-11-08)







