PolicyEngine US
For microsimulation, use policyengine.py. Society-wide microsimulation — population aggregates and distributional or budgetary impacts — is moving to the managed policyengine.py bundle, which pins certified, calibration-gated datasets. Direct microsimulation via policyengine-us (Microsimulation()) is deprecated and being migrated to policyengine.py. This package remains the home of the US tax-benefit rules and household-level calculations. Microsimulation results are estimates — inspect dataset calibration at https://calibration-diagnostics.vercel.app/populace.
PolicyEngine US is a microsimulation model of the US state and federal tax and benefit system.
PolicyEngine US supports Python 3.11 through 3.14 and requires pandas 3 or
later. To install, run pip install policyengine-us.
This release requires spm-calculator>=1.0.0,<=1.0.0.post1 (the canonical SPM threshold API).
Previously published country versions retain their original dependency metadata;
when reproducing one of those versions, include the compatible calculator
explicitly, for example:
uv pip install "policyengine-us==1.824.7" "spm-calculator==0.3.1"
To install PolicyEngine US as part of a certified PolicyEngine bundle, use the
bundle installer published by policyengine, for example:
uvx --from policyengine policyengine bundle install --country us --venv .venv
Statutes, forms and agency practice
When a statute conflicts with a regulation, form, instructions, manual or
stated agency practice, PolicyEngine US's rule is to follow the statute.
Forms and instructions fill gaps where the statute is silent. Each such
conflict is recorded in the source-conflict register that PolicyEngine shares
with the Axiom Foundation, including any code that does not follow the rule
yet: known-source-conflicts.yaml in
TheAxiomFoundation/rulespec-us.
For each conflict it gives what each source says, a worked example, the
reading this model takes and why, and the code and tests that implement it.
The code marks the deciding line with # Source conflict <jurisdiction>:<id>. See
CONTRIBUTING.md.
