Getting started - PolicyEngine UK documentation

PolicyEngine UK helps you analyse the UK tax and benefit system in two main ways: simulating policies for specific households, or running large-scale microsimulation analyses. The first requires just a few minutes of setup, while the second needs access to survey data and takes a bit longer to configure.

The full microsimulation model needs just this snippet:

!export HUGGING_FACE_TOKEN=<your_token>
!pip install policyengine-uk

Installing PolicyEngine UK¶

Install the package like any other Python library (requires Python ≥3.7):

pip install policyengine-uk

Your first household simulation¶

Let’s start with a simple example: calculating how much income tax a 30-year-old earning £30,000 would pay.

from policyengine_uk import Simulation

# Define the household situation
situation = {
    "people": {
        "person": {
            "age": {2025: 30},
            "employment_income": {2025: 30_000},
        },
    },
    "benunits": {
        "benunit": {
            "members": ["person"],
        },
    },
    "households": {
        "household": {
            "members": ["person"],
        }
    },
}

# Create and run the simulation
simulation = Simulation(situation=situation)
income_tax = simulation.calculate("income_tax", 2025)
print(f"Income tax: £{income_tax[0]:.2f}")

This gives us £3,486 in income tax.

Analysing a policy reform¶

Now let’s see what happens if we increase the basic rate of income tax from 20% to 25%:

# Define the policy reform
increase_basic_rate = {"gov.hmrc.income_tax.rates.uk[0].rate": 0.25}

# Compare baseline and reformed systems
baseline = Simulation(situation=situation)
reformed = Simulation(situation=situation, reform=increase_basic_rate)

baseline_tax = baseline.calculate("income_tax", 2025)[0]
reformed_tax = reformed.calculate("income_tax", 2025)[0]

increase = reformed_tax - baseline_tax
print(f"Tax increase: £{increase:.2f}")

The reform increases this person’s tax by £871.50 per year.

Running microsimulation analyses¶

Create a HuggingFace account.
If you need access to restricted UK datasets, first request access from PolicyEngine. Include your HuggingFace username and enough information to verify your licensed access to the underlying UK Data Service source data when you email contact@policyengine.org.
Once access has been granted, generate a personal access token in your HuggingFace settings.
Set it as an environment variable:

export HUGGING_FACE_TOKEN=your_token_here

Your first population analysis¶

Here’s how to calculate total Universal Credit spending across the UK:

from policyengine_uk import Microsimulation

# Load the enhanced Family Resources Survey data
sim = Microsimulation(
    dataset="hf://policyengine/policyengine-uk-data/enhanced_frs_2022_23.h5"
)

# Calculate total UC spending (in billions)
total_uc = sim.calculate("universal_credit", 2025).sum() / 1e9
print(f"Total Universal Credit spending: £{total_uc:.1f}bn")

This shows approximately £79.4bn in Universal Credit spending.

Estimating revenue from reforms¶

Let’s apply the same basic rate increase to the entire population:

# Set up baseline and reformed simulations
DATASET = "hf://policyengine/policyengine-uk-data/enhanced_frs_2022_23.h5"

baseline = Microsimulation(dataset=DATASET)
reformed = Microsimulation(dataset=DATASET, reform=increase_basic_rate)

# Calculate the revenue impact
baseline_income = baseline.calculate("household_net_income", 2025)
reformed_income = reformed.calculate("household_net_income", 2025)

revenue = -(reformed_income - baseline_income).sum() / 1e9
print(f"Additional revenue: £{revenue:.1f}bn per year")

The reform would raise approximately £35.5bn annually.

Working with complex households¶

Real households often have multiple people, children, and various income sources. Here’s a family with two adults and two children:

family_situation = {
    "people": {
        "parent_1": {
            "age": {2025: 35},
            "employment_income": {2025: 25_000},
        },
        "parent_2": {
            "age": {2025: 33},
            "employment_income": {2025: 15_000},
        },
        "child_1": {
            "age": {2025: 8},
        },
        "child_2": {
            "age": {2025: 5},
        },
    },
    "benunits": {
        "family": {
            "members": ["parent_1", "parent_2", "child_1", "child_2"],
        },
    },
    "households": {
        "home": {
            "members": ["parent_1", "parent_2", "child_1", "child_2"],
            "housing_costs": {2025: 9600},  # Annual rent
        }
    },
}

family_sim = Simulation(situation=family_situation)

# Calculate various benefits and taxes
child_benefit = family_sim.calculate("child_benefit", 2025)[0]
universal_credit = family_sim.calculate("universal_credit", 2025)[0]
total_tax = family_sim.calculate("income_tax", 2025).sum()

print(f"Child benefit: £{child_benefit:.2f}")
print(f"Universal Credit: £{universal_credit:.2f}")
print(f"Total income tax: £{total_tax:.2f}")

Next steps¶

You’re now ready to explore PolicyEngine UK further.

For more detailed guidance, see:

Simulations - comprehensive guide to running simulations
Scenarios - creating and combining policy reforms