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

CARTOframes v1.0.0 includes breaking changes from betas and 0.10 version, check the migration guide to learn how to update your code.


This guide is intended for those who are using CARTOframes for the first time and provides the steps to install it locally, in a Jupyter Notebook, or using a Virtual Environment.

Note: We collect data on your usage of CARTOframes to understand how you use it and use this information to improve the product. Usage data includes information like “map_created,” which tells us the date and time you created a map. The usage data we collect is anonymous, does not allow us to see the contents of what you’re working on, and is handled in accordance with our Privacy Notice . You may choose to opt out by calling cartoframes.utils.setup_metrics(False).

Install CARTOframes using pip

CARTOframes can be installed with pip by simply typing one of the following commands to do a system install:

To install the package:

pip install cartoframes

To upgrade the package to the latest version:

pip install --upgrade cartoframes

To install a specific version:

pip install cartoframes==1.x.y

Optional dependencies

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

Use a Jupyter Notebook

In the CARTOframes Developer Center, all of the examples are created with Jupyter Notebooks. If you aren’t familiar with Jupyter Notebooks, we recommend reading the beginner documentation to get familiar with the environment.

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

pip install cartoframes

Use a Virtual Environment

We recommend installing CARTOframes in a Virtual Environment, since they are very useful when working with Python locally. This section provides the necessary information to create a simple Virtual Environment and install CARTOframes inside of it:

$ virtualenv cartoframes_env
$ source cartoframes_env/bin/activate
(cartoframes_env) $ pip install cartoframes

When the virtual environment is activated, it is visible in the command line prompt, in this case: (cartoframes_env). It can be deactivated by typing deactivate to exit the virtualenv:

(cartoframes_env) $ deactivate

Use Jupyter Lab

Jupyter Lab does not install by default some requirements we need in this version of CARTOframes, so it requires to run also:

pip install ipywidgets
jupyter labextension install @jupyter-widgets/jupyterlab-manager