Synthea's five output formats, four of which are off until you edit a properties file
Synthetic Patient Population Simulator
At a glance
- What is it?
- Synthea generates synthetic but realistic patient records and health records in several formats, and the file is refreshingly specific about how to turn each one on. It is also quietly contradictory about the default: one paragraph says C-CDA is not produced unless you ask for it, and a later one says records come out in C-CDA and FHIR. The command line hides its most interesting capability in three unexplained flags.
- Who is it for?
- Use Synthea when you need realistic shaped health records without touching real patient data, and when you want control over the output rather than a single fixed format, because the exporters are switches in one properties file rather than separate tools. Do not adopt it expecting a turnkey dataset: the defaults are conservative, and a run that produces only FHIR is the documented behaviour rather than a fault.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 25 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- synthetichealth/synthea3,464 ★ · +105
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| synthetichealth/synthea | 3.4k | 3.5k |
105 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Four of the five formats are off, and one line says otherwise
The feature list advertises five output formats and every one of them except FHIR has to be switched on. HL7 FHIR is produced by default in R4, STU3 v3.0.1 or DSTU2 v1.0.2, so three different versions of the specification are available from the same generator. Bulk FHIR in ndjson needs exporter.fhir.bulk_data set to true, C-CDA needs exporter.ccda.export, CSV needs exporter.csv.export and CPCDS needs exporter.cpcds.export. The changing-defaults section says the same thing more bluntly, that by default Synthea does not generate CCDA, CPCDA, CSV or bulk FHIR, and that you must adjust the file at src/main/resources/synthea.properties to activate them. Then, further down, a single line says records will be output in C-CDA and FHIR formats in ./output, which contradicts the paragraph above it about C-CDA. Two smaller slips sit in the same text: that default-off sentence writes CPCDA where the feature list writes CPCDS.
Three flags do population snapshots and the help text never explains them
The usage block lists more than the four arguments the prose mentions. The prose says you can specify a state, city, population size or seed; the help output goes further with a referenceDate flag taking YYYYMMDD, a gender, a minimum and maximum age, an overflow population, a local config file path, a local modules directory, a clinician seed and a fixed record path. Three of those flags are the interesting ones and none has a description attached to it. An initial population snapshot path, an updated population snapshot path and an update time period in days together describe regenerating the same population later with changes applied over that period, which is how a longitudinal study gets continuity between separate runs instead of a fresh set of unrelated patients each time. A fourth flag, a path to keep matching patients, pairs with that mechanism. Then there is --config*=value, described only as any setting from src, which is the widest escape hatch the tool offers.
The Java requirement is a ceiling, not a floor
Most projects state a minimum runtime. This one states a preference about the maximum. The system requirements say Synthea requires Java JDK 17 or newer, then go on to strongly recommend using a Long-Term Support release of Java, 17 or 25, because issues may occur with more recent non-LTS versions. So a machine with a later Java installed is not disqualified by the first sentence and is discouraged by the second, which is an unusual thing to have to reason about when you are writing a Dockerfile or pinning a toolchain. The build itself is Gradle, and the quick start is three commands:
git clone https://github.com/synthetichealth/synthea.git
cd synthea
./gradlew build check testThe wrapper is committed, with a .bat variant for Windows. What that block does not show is the other half of the file's own advice, which is that anyone only wishing to run Synthea should follow a separate wiki page for basic setup instead of this developer path.
Three Gradle tasks exist for looking at the model rather than the data
Beyond building, the task list exposes reporting entry points that have nothing to do with generating patients. The graphviz task generates graphical visualisations of Synthea's rules and modules, and the same Graphviz machinery is part of how disease modules are drawn. The concepts task lists the concepts used in the records, and the attributes task lists the variables on each patient. That trio is the closest thing the repository offers to a map of its own model, and it earns its keep when you are writing a custom module and want to know what already exists rather than reinventing a concept with a slightly different name. The root also holds two shell entry points, run_synthea and a second script called run_flexporter whose purpose the file never explains, plus generate_samples.sh, which is likewise undocumented, alongside a config directory and a lib directory.
The default population is drawn from Massachusetts census data
The demographic default is stated once and it is specific. Statistics and demographics are configuration based, with defaults taken from Massachusetts Census data, so an unconfigured run is not a neutral population but one shaped by one state's numbers. That is the right trade for reproducibility, and it is the wrong default if you are testing anything that depends on regional variation, because the fix is to pass a state and optionally a city as positional arguments to run_synthea rather than to edit anything. The modelling scope around it is broad: a birth to death lifecycle, primary care, emergency room and symptom driven encounters, and records for conditions, allergies, medications, vaccinations, observations and vitals, labs, procedures and care plans. Rules are modular, with generic modules you can drop in and custom Java modules for anything they do not cover, and the local modules flag lets you point at your own directory.
The documentation is a wiki, and there is a web customiser for the properties file
The README is a summary that points outward three times before it explains anything. It opens by sending readers to the project wiki and to a Frequently Asked Questions page on that wiki, and the developer quick start then splits its audience explicitly, saying those instructions are for people wishing to examine the source, extend it or build it locally, and that everyone else should follow the basic setup and running instructions instead. The third pointer is the most useful of the three: a guided customiser tool hosted on the project's own pages, linked from the paragraph about changing default properties, which is a browser interface for the settings that otherwise mean editing synthea.properties by hand. That is a reasonable division of labour for a tool with this many switches, and it also means the wiki is the real documentation, which is worth knowing before you file an issue against the repository.
A rolling release tag sits next to the semantic ones
The release history has two shapes. Alongside versioned tags such as v4.0.0 from 2026-03-05 and v3.4.0 from 2025-11-05 there is a tag called master-branch-latest dated 2026-08-18T16:19:36Z, which is the same second as the last push in this tree, dated 2026-08-18T16:19:53Z. So one tag tracks the tip of the default branch continuously and the others mark deliberate versions, and a consumer pinning master-branch-latest gets whatever the branch contained at that moment rather than a reviewed release. The licensing is consistent across the repository and the manifest: Apache License 2.0, with the text in LICENSE, a NOTICE file beside it, and a copyright line reading Copyright 2017-2025 The MITRE Corporation. Note that the copyright range stops at 2025 while commits continued into 2026, which is a small thing but the kind of detail that dates a project snapshot.
Editorial conclusion
Use Synthea when you need realistic shaped health records without touching real patient data, and when you want control over the output rather than a single fixed format, because the exporters are switches in one properties file rather than separate tools. Do not adopt it expecting a turnkey dataset: the defaults are conservative, and a run that produces only FHIR is the documented behaviour rather than a fault. Three things to check first. Decide which format you actually need and read the file that switches it on, because four of the five are inert until you edit src/main/resources/synthea.properties, and the same file also says the population is drawn from Massachusetts census data by default, which matters if you are testing anything geography dependent. Read the Java requirement as a ceiling rather than a floor, since the file recommends a long term support release of 17 or 25 and warns that more recent non-LTS versions cause problems. And if your use case is governed by a compliance question, resolve that outside this repository, because it makes no claim about certification and only states that the records it produces are synthetic and not real.
Frequently asked questions
how to use synthea
Clone the repository and build it with ./gradlew build check test, or run the launcher directly with ./run_synthea. Arguments may be positional, a state and optionally a city, or flags such as -s for a seed, -p for the population size, -g for gender, -a for a minimum and maximum age, and -r taking YYYYMMDD. Full usage comes from passing -h.
What programming language is synthea written in?
Java, built with Gradle using a committed wrapper. It requires JDK 17 or newer, prefers a long term support release of 17 or 25, and takes additional capabilities as custom Java rule modules alongside the generic modules you can drop in.
Is Synthea HIPAA compliant?
This repository makes no claim about certification or compliance. What it states is the premise such a question rests on: the goal is to output synthetic, realistic but not real, patient data, with configuration based statistics and demographics defaulting to Massachusetts Census data.
What is Synthea data?
Records produced by a synthetic patient population simulator: a birth to death lifecycle with primary care, emergency room and symptom driven encounters, exportable as HL7 FHIR in R4, STU3 v3.0.1 or DSTU2 v1.0.2, plus C-CDA, CSV, CPCDS and bulk ndjson once their exporter switches are turned on.
Is Synthea free to use?
The repository is published under the Apache License 2.0, with the licence text and a NOTICE file at the root and a copyright line reading Copyright 2017-2025 The MITRE Corporation. The file says nothing about cost, support or hosting, so any question beyond the licence terms is not answered here.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/synthetichealth-synthea)Star history chart for your README
[](https://hysenlabs.com/projects/synthetichealth-synthea)Was this useful?