A Python package for integrating CARTO maps, analysis, and data services into data science workflows.

This component is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our new Python packages here.

View source


Welcome! This guide contains the information you need to install CARTOframes.

System requirements

Operating system

Windows, macOS, GNU/Linux

Python interpreter

Python 3.5+ (previous versions are not supported)

You can check your version by running:

python --version

If you don’t have Python installed, please install the latest version from python.org or refer to the Installing Python guide.

Python environments

Although installing a Python environment is not strictly required, it’s highly recommended to have cleaner and more organized installations. You can check the tutorial on Creating Virtual Environments or Managing Conda Environments.

Install it with pip

The latest stable version of CARTOframes may be installed or upgraded via pip (Python Package Manager) by running one of the following commands:

Install the package:

pip install cartoframes

Upgrade the package to the latest version:

pip install --upgrade cartoframes

Install a specific version:

pip install cartoframes==1.x.y

If pip does not exist, you have to install it manually. See https://pip.pypa.io/en/stable/installing/.

Optional Dependencies

RTree is a spatial index package to improve performance and is required for overlay operations. It provides an interface to libspatialindex.

Windows users

CARTOframes needs that Shapely and Fiona libraries are already installed in your system. Execute these commands to install CARTOframes correctly:

pip install shapely
conda install -c conda-forge fiona
pip install cartoframes

Use Jupyter Notebooks

CARTOframes is created to run in Jupyter Notebooks, which allows rendering powerful HTML visualizations. If you are not familiar with Jupyter Notebooks, we recommend reading this introduction.

To install CARTOframes through a Jupyter Notebook, run this command:

!pip install cartoframes

About metrics

We collect data on the usage of CARTOframes to improve the library. Usage data includes information like “map_created,” which is the event triggered when a map is created. The collected usage data is anonymous and it does not contain the data processed, just the information of the event, and it’s handled in accordance with our Privacy Notice https://carto.com/privacy/ . You may choose to opt out by calling cartoframes.utils.setup_metrics(False).