Install & Compatibility
Where this runs
tested against v1.729.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 35.1s · import 40.793s · 679MB
690MB installed
● package 690MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
system
✓ from policyengine_us import system
Person
✓ from policyengine_core.entities import Person
Household
✓ from policyengine_core.entities import Household
Simulation
✓ from policyengine_core.simulation import Simulation
✗ from openfisca_us.simulation import Simulation
The library was renamed from openfisca-us to policyengine-us in November 2022. Core components also moved to policyengine_core.
This quickstart demonstrates how to define a simple household, retrieve the current US tax-benefit system, run a simulation to calculate a person's net income, and then apply a basic policy reform (Universal Basic Income) to see its impact.
from policyengine_us import system
from policyengine_core.entities import Person, Household
from policyengine_core.simulation import Simulation
# Define a simple household
# A person named 'alice' who is 40 years old and has wage income
alice = Person(age=40, wages=50000, employment_status='EMPLOYED')
# A household with Alice
household = Household(members=[alice])
# Get the current US tax-benefit system
# By default, uses the latest available policy year (e.g., 2025 as of recent updates)
sim_system = system.get_system()
# Create a simulation for the household
simulation = Simulation(household=household, system=sim_system)
# Calculate a variable, e.g., Alice's net income in 2025
alice_net_income = simulation.get_person_variable(person_id=alice.id, variable_name='net_income', period='2025')
print(f"Alice's net income in 2025: ${alice_net_income:,.2f}")
# Example of applying a simple reform (e.g., a universal basic income)
reform_code = {
'universal_basic_income': [
{
'period': '2025',
'value': 12000,
'description': 'A universal basic income of $12,000 per year for all adults.'
}
]
}
# Apply the reform to the system
reformed_system = system.get_system(reform=reform_code)
# Run simulation with the reformed system
reformed_simulation = Simulation(household=household, system=reformed_system)
alice_net_income_reformed = reformed_simulation.get_person_variable(
person_id=alice.id, variable_name='net_income', period='2025'
)
print(f"Alice's net income in 2025 with UBI reform: ${alice_net_income_reformed:,.2f}")
policyengine --version
Debug
Known issues
breakingThe library was renamed from `openfisca-us` to `policyengine-us` in November 2022. This included changes to package names and core import paths.fixUpdate all import statements from `openfisca_us` or `openfisca_core` to `policyengine_us` and `policyengine_core` respectively.
affects: < 1.0 (before Nov 2022)
gotchaPolicyEngine US relies on complex underlying data, which can have caveats. For example, population impact analyses using the Current Population Survey (CPS) may have truncated high incomes or underestimated benefits. Policy may also be applied to older data years (e.g., 2022 policy on 2020 data).fixAlways review the data source and its limitations described in the PolicyEngine documentation. Understand that microsimulation models are approximations and consult official sources for definitive figures.
affects: All versions
gotchaKnown issues exist with state-specific tax calculations and non-conformity to federal changes (e.g., for Maine, DC, South Carolina). This can lead to discrepancies compared to other tax simulators like TAXSIM35.fixFor highly precise state-level analysis, cross-verify results with other sources or consult PolicyEngine's GitHub issues for known limitations and ongoing fixes.
affects: All versions
gotchaWhen developing with `policyengine-us-data` (often used for generating microdata), a dependency on `torch` for certain machine learning features can cause unexpected test failures or installation issues if not properly handled in the environment.fixIf encountering issues related to `policyengine-us-data` or `torch`, ensure `torch` is correctly installed, or consider using pre-generated datasets if extensive data manipulation is not required. Review `policyengine-us-data`'s specific installation instructions if directly developing with it.
affects: Versions requiring `policyengine-us-data` for L0 penalty features (specific versions not fully specified but noted as a breaking change in issue #6303)
gotchaPolicyEngine's REST API (used if you integrate with their external service) requires client ID/secret for authentication tokens, which expire monthly. This can lead to 'Authorization failed' errors if not regularly refreshed.fixImplement a token refresh mechanism in your application to obtain a new authentication token before the current one expires.
affects: All versions interacting with the PolicyEngine REST API
Audit
Dependencies
policyengine-corerequiredCore microsimulation framework.
policyengine-us-dataoptionalProvides microdata for simulations; can introduce complex dependencies like `torch` for specific features.