geobr: Download Official Spatial Data Sets of Brazil

The package is currently available in R and Python.

R	Python	Repo

Installation R

# From CRAN
install.packages("geobr")

# or use the development version with latest features
utils::remove.packages('geobr')
remotes::install_github("ipea/geobr", subdir = "r-package")

obs. If you use Linux, you need to install a couple dependencies before installing the libraries sf and geobr.More info here.

Installation Python

uv is the recommended installer. From your project directory (run uv init first if you don’t have a pyproject.toml yet):

uv add geobr

Alternatively, with pip:

pip install geobr

Windows users:

conda create -n geo_env
conda activate geo_env  
conda config --env --add channels conda-forge  
conda config --env --set channel_priority strict  
conda install python=3 geopandas  
uv add geobr

Basic Usage

The syntax of all geobr functions operate on the same logic so it becomes intuitive to download any data set using a single line of code. Like this:

R, reading the data as an sf object

library(geobr)

# Read specific municipality at a given year
mun <- read_municipality(code_muni = 1200179, year = 2022)

# Read all municipalities of given state at a given year
mun <- read_municipality(code_muni = "RJ", year = 2022) # or
mun <- read_municipality(code_muni = 33, year = 2022)

# Read all municipalities in the country at a given year
mun <- read_municipality(code_muni="all", year = 2022)

More examples in the intro Vignette

Python, reading the data as a geopandas object

from geobr import read_municipality

# Read specific municipality at a given year
mun = read_municipality(code_muni=1200179, year=2017)

# Read all municipalities of given state at a given year
mun = read_municipality(code_muni=33, year=2010) # or
mun = read_municipality(code_muni="RJ", year=2010)

# Read all municipalities in the country at a given year
mun = read_municipality(code_muni="all", year=2018)

Since v1.0.0, the Python package uses a GeoParquet pipeline. For DuckDB workflows, use query() to load and analyze snapshots directly in SQL.

Python, DuckDB SQL and spatial analysis

Run SQL across geobr snapshots. Missing views are downloaded automatically on first use.

from geobr import query, to_geopandas

# Filter a snapshot (auto-downloads states_2020 on first use)
query("""
    SELECT name_state, abbrev_state
    FROM states_2020
    WHERE abbrev_state = 'RJ'
""").df()

# Spatial join across datasets
query("""
    SELECT count(*) AS schools_in_amazon
    FROM schools_2020 s
    JOIN biomes_2019 b ON ST_Within(s.geometry, b.geometry)
    WHERE b.name_biome ILIKE '%Amaz%'
""").df()

# Round-trip to GeoPandas for plotting
gdf = to_geopandas("states_2020")

More examples in python-package/examples, including duckdb_demo.ipynb.

Available datasets:

You can check all the data sets available with `list_geobr()

Function	Geographies available	Source	Years available
read_amazon	Brazil’s Legal Amazon	MMA	2019, 2020, 2021, 2022, 2024
read_biomes	Biomes	IBGE	2006, 2019, 2025
read_census_tract	Census tract (setor censitário)	IBGE	2000, 2010, 2022
read_conservation_units	Environmental Conservation Units	MMA	202402, 202503
read_country	Country	IBGE	1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025
read_disaster_risk_area	Disaster risk areas	CEMADEN and IBGE	2010
read_favelas	Favelas and urban communities	IBGE	2022
read_health_facilities	Health facilities	CNES, DataSUS	201704, 201707, 201710, 201801, 201804, 201807, 201810, 201901, 201904, 201907, 201910, 202001, 202004, 202007, 202010, 202101, 202104, 202107, 202110, 202201, 202204, 202207, 202210, 202301, 202304, 202307, 202310, 202401, 202404, 202407, 202410, 202501, 202504, 202507, 202510, 202601, 202604
read_health_region	Health regions and macro regions	DataSUS	1991, 1994, 1997, 2001, 2005, 2013, 2023, 2024, 2025
read_immediate_region	Immediate region	IBGE	2019, 2020, 2021, 2022, 2023, 2024, 2025
read_indigenous_land	Indigenous lands	FUNAI

point_right: All datasets use geodetic reference system “SIRGAS2000”, CRS(4674).

Other support functions:

Function	Action
list_geobr	List all datasets available in the geobr package
lookup_muni	Look up municipality codes by their name, or the other way around
remove_islands	Removes distant oceanic islands from Brazil
grid_state_correspondence_table	Loads a correspondence table indicating what quadrants of IBGE’s statistical grid intersect with each state
cep_to_state	Determine the state of a given CEP postal code
…	…

Note 1. Data sets and Functions marked with “dev” are only available in the development version of geobr.

Note 2. Most data sets are available at scale 1:250,000 (see documentation for details).

Contributing to geobr

If you would like to contribute to geobr and add new functions or data sets, please check this guide to propose your contribution.

---

Related projects

As of today, there there are no other R or Python computational packages similar to geobr. The geobr package makes different contributions to the community, including for example:

• Access to a wider range of official spatial data sets, such as states and municipalities, census tracts, urbanized areas, etc
• A consistent syntax structure across all functions, making the package very easy and intuitive to use
• Access to spatial data sets with updated geometries for various years
• Harmonized attributes and geographic projections across geographies and years
• Option to download geometries with simplified borders for fast rendering
• Option to download geometries as geoarrow objects out of memory
• Stable version published on CRAN for R users, and on PyPI for Python users

Similar packages for other countries/continents

• Africa: afrimapr
• Argentina: geoAr
• Brazil: geobr
• Canada: cancensus
• Chile: chilemapas
• Czech Republic: RCzechia
• Finland: geofi
• Kazakhstan: (geokz)[https://github.com/arodionoff/geokz]
• Peru: mapsPERU
• Spain: mapSpain
• UK: geographr
• Uruguay: geouy
• USA: tigris
• Global (political administrative boundaries): rgeoboundaries

---

Credits

Original shapefiles are created by official government institutions. The geobr package is developed by a team at the Institute for Applied Economic Research (Ipea), Brazil. The package received support from Instituto Todos pela Saúde (ITpS). If you want to cite this package, you can cite it as:

• Pereira, R.H.M.; Barbosa, R.J.; et. all (2026) geobr: Download Official Spatial Data Sets of Brazil. v2.0.0 GitHub repository - https://github.com/ipea/geobr.