Installation

Installer cartograpy et préparer son environnement Python.

Cette page présente le parcours d’installation recommandé pour utiliser cartograpy en local.

Pré-requis

  • Python 3.11 ou supérieur
  • Un environnement virtuel dédié (venv, conda ou uv)
  • Les bibliothèques système requises par geopandas, rasterio et cartopy (GDAL, GEOS, PROJ) : voir la section par plateforme ci-dessous

Installation rapide

cartograpy est publié sur PyPI : il n’existe pas de paquet conda-forge, donc conda/uv servent ici à créer l’environnement, pip reste l’outil qui installe cartograpy lui-même.

pip install cartograpy
conda create -n cartograpy python=3.11
conda activate cartograpy
pip install cartograpy
Astuce

Sur Windows, si pip install cartograpy échoue à cause de GDAL/GEOS/PROJ, installez d’abord ces dépendances binaires via le canal conda-forge (voir la section Dépendances par plateforme ci-dessous) avant de relancer pip install cartograpy dans l’environnement conda.

uv venv --python 3.11
uv pip install cartograpy

Dans un projet géré par uv (avec pyproject.toml) :

uv add cartograpy

Installation pour le développement

git clone https://github.com/mr-kam/cartograpy.git
cd cartograpy
pip install -e .[dev]

[dev] ajoute pytest, ruff, mypy et jupyterlab : nécessaires pour contribuer, inutiles pour un simple usage du package.

Dépendances par plateforme

Les roues précompilées (.whl) de geopandas, rasterio, cartopy et pyproj couvrent la majorité des cas via pip install cartograpy directement : aucune compilation locale requise dans la plupart des configurations récentes de Python 3.11+/pip.

Astuce

En cas d’échec d’installation (erreurs de compilation liées à GDAL/GEOS/PROJ), passez par conda/mamba (canal conda-forge) qui gère ces dépendances binaires plus fiablement que pip sur Windows :

conda install -c conda-forge geopandas rasterio cartopy
pip install cartograpy --no-deps
pip install cartograpy  # puis les dépendances Python restantes

Installez GDAL/GEOS/PROJ via Homebrew avant pip install cartograpy si vous n’utilisez pas de roues précompilées :

brew install gdal geos proj
pip install cartograpy

Selon la distribution, installez les bibliothèques de développement avant pip install cartograpy :

# Debian / Ubuntu
sudo apt-get install libgdal-dev libgeos-dev libproj-dev

pip install cartograpy

Dépendances importantes

  • geopandas pour les données vectorielles
  • rasterio pour les rasters
  • cartopy et matplotlib pour les cartes statiques
  • geohexgrid pour les grilles hexagonales / hexbin
  • scienceplots et mplcyberpunk pour les styles graphiques de styling

Les sources de données en ligne et les cartes interactives sont des extras optionnels, à ajouter selon vos besoins :

Extra Fonctionnalité Paquets installés
osm OSM, géocodage via OSM osmnx
worldbank WorldBank wbdata
gee Gee (Google Earth Engine) earthengine-api, geemap
stac STAC (Planetary Computer…) pystac-client, planetary-computer
webmap WebMap folium, lonboard, pyarrow, keplergl (Python < 3.13), rio-tiler
all tout ce qui précède 
pip install cartograpy[osm,stac]   # ou cartograpy[all]

Voir Sources de données et dépendances pour la liste complète et les dépendances optionnelles (contextily, matplotlib-scalebar).

Jupyter et Marimo

Aucun environnement de notebook n’est installé avec cartograpy : ajoutez celui que vous utilisez.

pip install cartograpy[notebook]   # installe jupyter
jupyter lab
pip install marimo
marimo edit mon_notebook.py

Vérifier l’installation

import cartograpy as cp

print(cp.__version__)                  # ex. "3.0.2"
print(cp.COUNTRY_ISO3["france"])       # "fra"
Note

Si cet import échoue avec une erreur liée à GDAL, GEOS ou PROJ, le problème vient des dépendances système (voir la section par plateforme ci-dessus), pas de cartograpy lui-même.

Ou, sans écrire de Python, via la CLI installée avec le paquet :

cartograpy doctor

Vérifie Python, GDAL/PROJ/GEOS, les dépendances cœur et celles des extras optionnels (webmap, osm, worldbank, gee, stac) en un coup d’œil. Voir Reference CLI.