Skip to main content
v2026.11,986 entries · CC-BY 4.0

Synthea: Synthetic Patient Generator, Setup and Output Guide

How to install and run Synthea, MITRE’s open-source synthetic patient generator, and how to enable and read its FHIR and CSV output.

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.

Ask your first question freeSubscribe

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).

  1. Jar route (basic setup): install JDK 17 or newer, then download synthea-with-dependencies.jar from the project’s master-branch-latest release.
  2. Source route (developer setup): run git clone https://github.com/synthetichealth/synthea.git, then cd synthea, then ./gradlew build check test. On Windows use .gradlew.bat build check test.

Run it: step by step

  1. Print the usage text. Jar: java -jar synthea-with-dependencies.jar -h. Source: ./run_synthea -h (Windows: .
    un_synthea.bat
    ).
  2. Generate a default population. Jar: java -jar synthea-with-dependencies.jar. Source: ./run_synthea -p 1000 sets the population size to 1,000.
  3. Choose a place. Give a state, and optionally a city, as positional arguments after the options: ./run_synthea Massachusetts or ./run_synthea -s 12345 -p 1000 Utah "Salt Lake City". Quote any argument that contains spaces.
  4. 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).
  5. Find the output. By default files go to an output folder (the exporter.baseDirectory setting, 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=value options.
  • Expected CSV or C-CDA files are missing: those exporters are off by default; enable them with the switches above.
  • More records than -p: -p sets living patients, and patients who die during the simulation are also exported, so totals can be higher.
  • Results differ between runs: set the same -s seed 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

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Synthea: Synthetic Patient Generator, Setup and Output Guide

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →