Configuration

Configuration

Synthea is configured via a synthea.properties file. The built-in defaults live at resources/synthea.properties; pass a custom file with -c path/to/file.properties.

Using a Configuration File

uv run synthea -c my-config.properties -p 100

Settings in your file override the built-in defaults. You only need to include the keys you want to change.

Full Reference

Exporter settings

# FHIR R4 output (default: true)
exporter.fhir.export = true

# CSV tabular output (default: false)
exporter.csv.export = false

# Raw JSON output (default: false)
exporter.json.export = false

# Output root directory
exporter.baseDirectory = ./output/

# Use UUID filenames instead of patient names
exporter.use_uuid_filenames = false

# Append to existing files instead of overwriting
exporter.append_mode = false

# Include only living patients in export
exporter.only_living = false

# FHIR server URL to POST bundles (empty = write files only)
exporter.fhir.server_url =

# FHIR bundle type: transaction or collection
exporter.fhir.transaction_bundle = true

Generator settings

# Default population size when -p is not specified
generate.default_population = 10

# Thread pool size (use 1 for reproducibility with a seed)
generate.thread_pool_size = 4

# Generate only deceased patients
generate.only_dead_patients = false

# Max attempts to produce a patient that matches demographic criteria
generate.max_attempts_to_keep_patient = 1000

# Time step for simulation in milliseconds (default: 1 week)
generate.timestep = 604800000

# Reference year for age calculations (default: current year)
generate.reference_year = 2026

Cost settings

# Default costs when no payer-specific cost data is found
generate.costs.default_procedure_cost = 500.0
generate.costs.default_medication_cost = 255.0
generate.costs.default_encounter_cost = 125.0
generate.costs.default_immunization_cost = 136.0

Geographic settings

# Default state when none is specified
generate.geography.state = Massachusetts

# Restrict city selection within the chosen state
generate.geography.city =

# Use real demographic distributions from census data
generate.geography.use_demographics = true

Module settings

# Comma-separated list of modules to enable (empty = all)
generate.modules.enabled =

# Comma-separated list of modules to disable
generate.modules.disabled =

Insurance / payer settings

# Percentage of patients with no insurance (0.0–1.0)
generate.payers.insurance_uninsured_rate = 0.08

# Transition age from CHIP to adult insurance
generate.payers.insurance_transition_year = 26

Example: FHIR-only export with a remote server

exporter.fhir.export = true
exporter.csv.export = false
exporter.json.export = false
exporter.fhir.server_url = https://fhir.example.com/r4
exporter.fhir.transaction_bundle = true
generate.thread_pool_size = 8
generate.default_population = 500

Example: Large population benchmark

generate.thread_pool_size = 16
generate.default_population = 10000
exporter.use_uuid_filenames = true
exporter.baseDirectory = /data/synthea-output/
exporter.fhir.export = true
exporter.csv.export = true

Programmatic Configuration Override

You can override any property at runtime via the Python API:

from synthea.helpers.config import Config

config = Config("resources/synthea.properties")
config.set("exporter.fhir.export", "true")
config.set("generate.thread_pool_size", "8")