Installation#

Standard Installation#

The simplest way to install city2graph is via pip:

# Basic installation (without PyTorch)
pip install city2graph

This installs the core functionality without PyTorch and PyTorch Geometric.

Warning

Conda distributions are deprecated for PyTorch and PyTorch Geometric due to limited demand and compatibility issues. We recommend using pip or uv for the most reliable installation experience.

With PyTorch (CPU)#

If you need the graph neural network functionality, install with the torch option:

# Install with PyTorch and PyTorch Geometric (CPU version)
pip install "city2graph[torch]"

This will install PyTorch and PyTorch Geometric with CPU support.

Note

The PyTorch Geometric extensions (pyg_lib, torch_scatter, etc.) are not included in the [torch] extra and must be installed separately as shown in the CUDA/GPU section below.

With PyTorch + CUDA (GPU)#

For GPU acceleration with a specific CUDA version, we recommend installing PyTorch and PyTorch Geometric separately before installing city2graph:

Step 1: Install PyTorch with your desired CUDA version

pip install torch=={TORCH_VERSION} --index-url https://download.pytorch.org/whl/{CUDA_VERSION}

Step 2: Install PyTorch Geometric and its CUDA dependencies

pip install torch_geometric
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-{TORCH_VERSION}+{CUDA_VERSION}.html

Step 3: Install city2graph (it will detect the pre-installed PyTorch)

pip install city2graph

Replace {TORCH_VERSION} with the desired PyTorch version (e.g., ‘2.4.0’ or above) and {CUDA_VERSION} with your CUDA version (e.g., ‘cu121’ for CUDA 12.1). You can find the appropriate versions on the PyTorch website and PyTorch Geometric website.

Note

The core package of PyTorch Geometric (torch_geometric) is independent from CUDA or CPU. However, the extensions (pyg_lib, torch_scatter, etc.) are CUDA-specific.

Using uv#

If you’re using uv for dependency management, you can install city2graph from the source:

Step 1: Clone the repository and install base dependencies

git clone https://github.com/c2g-dev/city2graph.git
cd city2graph
uv sync

Step 2: Install with PyTorch support (optional)

uv sync --group torch

or if you want to install with a specific PyTorch version:

uv sync --group torch --index https://download.pytorch.org/whl/{CUDA_VERSION}

Step 3: Install PyG extensions for CUDA support (if needed)

uv add pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv --index https://data.pyg.org/whl/torch-{TORCH_VERSION}+{CUDA_VERSION}.html

Step 4: Install development dependencies (optional)

uv sync --group dev

Step 5: Run commands with uv

uv run python your_script.py
uv run jupyter notebook

Note

uv handles dependency resolution more efficiently than Poetry and can install PyTorch Geometric extensions directly through index URLs.

Requirements#

city2graph requires the following packages:

  • networkx

  • shapely

  • geopandas

  • libpysal

  • momepy

  • overturemaps

For graph neural network functionality, you’ll also need:

  • torch

  • torch_geometric

  • pyg_lib

  • torch_scatter

  • torch_sparse

  • torch_cluster

  • torch_spline_conv