Skip to content

PyPUMS

Python interface to the US Census Bureau API — American Community Survey, Decennial Census, PUMS microdata, population estimates, and migration flows.

What is PyPUMS?

PyPUMS gives you programmatic access to US Census Bureau data directly from Python. Query the Census API, get back pandas DataFrames (or GeoDataFrames with geometries), and start analyzing immediately.

import pypums

# Median household income by county in California
df = pypums.get_acs(
    geography="county",
    variables=["B19013_001"],
    state="CA",
    year=2023,
)
print(df.head())

     GEOID               NAME      variable  estimate     moe
0  06001  Alameda County, ...  B19013_001  113650.0  1282.0
1  06003   Alpine County, ...  B19013_001   72857.0  9631.0
2  06005   Amador County, ...  B19013_001   71346.0  4076.0
3  06007    Butte County, ...  B19013_001   56219.0  1775.0
4  06009 Calaveras County, ...  B19013_001   70587.0  5047.0

Key Features

  • Five data sources

    get_acs() · get_decennial() · get_pums() · get_estimates() · get_flows()

    Guides

  • Spatial support

    Add geometry=True to any query and get a GeoDataFrame with cartographic boundary shapes (via pygris, cached locally).

    Spatial guide

  • Variable discovery

    Browse and search thousands of Census variables with load_variables().

    Finding variables

  • MOE calculations

    Built-in margin of error functions for derived estimates, following Census Bureau formulas.

    MOE guide

  • Survey design

    SurveyDesign class with replicate-weight standard errors for PUMS microdata.

    Survey design

  • CLI access

    Query Census data from the command line with pypums acs, pypums decennial, and more.

    CLI reference

Quick Install

uv add pypums

For spatial/mapping support:

uv add "pypums[spatial]"

You’ll need a free Census API key.

Full installation guide

Where to Start

I want to… Start here
Get Census data into a DataFrame quickly Quick Start
Figure out which dataset I need Census 101
Find the right variable codes Finding Variables
Make a choropleth map Spatial Guide
Work with PUMS microdata PUMS Guide
Migrate from R/tidycensus tidycensus Migration
Migrate from old PyPUMS (ACS class) Migration Guide
Look up a function signature API Reference