Installation

This guide is intended for those who are using CARTOframes for the first time. It covers:

• The Python version required
• How to install it using pip
• How to install it in a Jupyter Notebook
• How to install it in Windows
• How to create a Virtual Enviroment
• Considerations in Jupyter Lab
• Metrics

We recommend installing CARTOframes in a Virtual Environment, since they are very useful when working with Python locally.

Python version required

CARTOframes needs Python 3 to work properly. You can check your version by running:

python --version

You should get some output like Python 3.6.3. If you do not have Python, please install the latest 3.x version from python.org or refer to the Installing Python section of the Hitchhiker’s Guide to Python.

Install it 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 dependency

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

Install it in 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

Install it in Windows

In order to work properly, 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 a Virtual Environment

This section provides the necessary information to create a simple Virtual Environment with virtualenv and conda and also how to 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

Conda users

Let's see how to achieve it with conda.

$ conda create --name cartoframes_env
$ conda activate cartoframes_env
(cartoframes_env) $ pip install shapely
(cartoframes_env) $ conda install -c conda-forge fiona
(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) $ conda 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

Metrics

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 https://carto.com/privacy/ . You may choose to opt out by calling cartoframes.utils.setup_metrics(False).