Status:Active CRAN_Status_Badge R build
status Codecov test

ipumsr provides an R interface for handling IPUMS data, allowing users to:


To install the package from CRAN, use


To install the development version of the package, use


What is IPUMS?

IPUMS is the world’s largest publicly available population database, providing census and survey data from around the world integrated across time and space. IPUMS integration and documentation make it easy to study change, conduct comparative research, merge information across data types, and analyze individuals within family and community context. Data and services are available free of charge.

IPUMS consists of multiple projects, or collections, that provide different data products.

ipumsr supports different levels of functionality for each IPUMS project:

| Project / Collection | Data Type | Description | Read Data Extracts | Request & Download Data | Get Metadata | |:----------------------------------------------------------------------|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------|:------------------------|:-------------| | IPUMS USA | Microdata | U.S. Census and American Community Survey microdata (1850-present) | X | X | | | IPUMS CPS | Microdata | Current Population Survey microdata including basic monthly surveys and supplements (1962-present) | X | X | | | IPUMS International | Microdata | Census microdata covering over 100 countries, contemporary and historical | X | X | | | IPUMS NHGIS | Aggregate Data | Tabular U.S. Census data and GIS mapping files (1790-present) | X | X | X | | IPUMS IHGIS | Aggregate Data | Tabular and GIS data from population, housing, and agricultural censuses around the world | | | | | IPUMS Time Use | Microdata | Time use microdata from the U.S. (1930-present) and thirteen other countries (1965-present) | X | | | | IPUMS Health Surveys | Microdata | Microdata from the U.S. National Health Interview Survey (NHIS) (1963-present) and Medical Expenditure Panel Survey (MEPS) (1996-present) | X | | | | IPUMS Global Health | Microdata | Health survey microdata for low- and middle-income countries, including harmonized data collections for Demographic and Health Surveys (DHS) and Performance Monitoring for Action (PMA) surveys | X | | | | IPUMS Higher Ed | Microdata | Survey microdata on the science and engineering workforce in the U.S. from 1993 to 2013 | X | | |

ipumsr uses the IPUMS API to submit data requests, download data extracts, and get metadata, so the scope of ipumsr functionality generally corresponds to the available API functionality. As the IPUMS team extends the API to support more functionality for more projects, we aim to extend ipumsr capabilities accordingly.

Getting started

If you’re new to IPUMS data, learn more about what’s available through the IPUMS Projects Overview.

For an overview of how to find, request, download, and read IPUMS data into R, see IPUMS Data and R.

To learn how ipumsr interfaces with the IPUMS extract system via the IPUMS API, see the Introduction to the IPUMS API for R Users.

Additional demonstration vignettes are also available as Articles on the package website or by using the vignette() function in R (e.g. vignette("ipums-read", package = "ipumsr")). These include vignettes for accessing microdata and NHGIS data and metadata via the API.

The IPUMS support website also houses many project-specific R-based training exercises. (As of September 2023, these exercises have not yet been updated to incorporate the major API data and metadata access capabilities added to ipumsr in version 0.6.0.)

Related work

Getting help + contributing

We greatly appreciate feedback and development contributions. Please submit any bug reports, pull requests, or other suggestions on GitHub. Before contributing, please be sure to read the Contributing Guidelines and the Code of Conduct.

If you have general questions or concerns about IPUMS data, check out our user forum or send an email to

Try the ipumsr package in your browser

Any scripts or data that you put into this service are public.

ipumsr documentation built on Oct. 20, 2023, 5:10 p.m.