City2Graph: Geospatial Graphs for Network Analysis and GNNs
City2Graph is a Python library that turns buildings, streets, public transport feeds, origin–destination matrices, zones, and points of interest into spatial and heterogeneous graphs. It bridges GeoPandas, NetworkX, and PyTorch Geometric so the same geospatial data can support network analysis, urban research, and Graph Neural Networks (GNNs). See the documentation for installation, tutorials, and the Python API reference.
Features
- Morphology: Graphs of buildings, streets, and tessellated urban fabric from OpenStreetMap and Overture Maps.
- Transportation: GTFS public transport and GBFS shared-mobility feeds loaded into DuckDB, with GTFS aggregated into stop-to-stop transit graphs.
- Mobility: Origin–destination matrices and flow data — migration, bike-sharing, pedestrian counts — as weighted spatial graphs.
- Proximity and Contiguity: KNN, Delaunay, Gilbert, and Waxman graphs plus queen/rook contiguity, under Euclidean, Manhattan, or network distances.
- Heterogeneous Graphs and Metapaths: Multiple node and edge types in one graph, with metapath-derived edges composing relations across them.
- GNN-ready Tensors: Round-trip conversion between GeoDataFrames, NetworkX, and PyTorch Geometric
Data/HeteroData.
Installation
Using pip
Basic Installation
City2Graph supports Python 3.12–3.14. The simplest way to install it is via pip:
pip install city2graph
This installs the core functionality without PyTorch and PyTorch Geometric.
With PyTorch (CPU)
If you need the Graph Neural Networks functionality, install with the cpu option:
pip install "city2graph[cpu]"
This will install PyTorch and PyTorch Geometric with CPU support, suitable for development and small-scale processing.
With PyTorch + CUDA (GPU)
For GPU acceleration, you can install City2Graph with a specific CUDA version extra. For example, for CUDA 13.0:
pip install "city2graph[cu130]"
Supported CUDA versions are cu126, cu128, and cu130.
The cpu, cu126, and cu130 extras use PyTorch 2.13 or newer. Because
PyTorch no longer publishes CUDA 12.8 wheels past 2.11, cu128 uses PyTorch 2.11.
Using conda
Basic Installation
You can also install City2Graph using conda from conda-forge:
conda install -c conda-forge city2graph
This installs the core functionality without PyTorch and PyTorch Geometric.
With PyTorch (CPU)
To use PyTorch and