PyTorch Geometric: Strengths, Weaknesses, and What It Doesn't Cover

PyTorch Geometric (PyG) is the most widely adopted GNN library in the research community. It provides a large collection of graph neural network layers, standard benchmark datasets, and useful utilities for graph learning. It is also an honest choice to make when working on standard GNN tasks. This article is a balanced technical assessment — where PyG is genuinely strong, where it has real limitations, and what falls outside its scope.

This is not a sales pitch for any alternative. The goal is to give researchers a clear map for choosing their tools, including knowing when PyG is exactly right and when you might need something different.

---

What PyG Does Well

Dataset coverage. PyG includes adapters for a wide range of graph benchmark datasets — TU datasets, OGB, ZINC, QM9, citation networks (Cora, Citeseer, PubMed), and many others. This breadth is genuinely useful for benchmarking.

Layer library. PyG ships over 50 GNN layer types, covering GCN, GAT, GATv2, GraphSAGE, GIN, APPNP, PNA, DiffPool, and many more. If your research requires comparing many architectures on the same task, having them in one library reduces integration friction.

Message passing framework. PyG's MessagePassing base class provides a clean abstraction for implementing custom GNN layers. The propagate / aggregate / update separation encourages well-structured code.

Mini-batch sampling. NeighborLoader, GraphSAINT, Cluster-GCN, LinkNeighborLoader — PyG has mature implementations of scalable sampling strategies backed by C++/Rust extensions for speed.

Community and documentation. PyG has a large user base, extensive tutorials, active GitHub issues, and good documentation. Finding help with standard tasks is relatively easy.

Integration with OGB and benchmarks. PyG is the de-facto choice for OGB evaluators, leaderboard submissions, and many published baselines. If your work needs to reproduce a published PyG result, using PyG is the obvious path.

---

Known Limitations of PyG

Node features must be 2-D vectors. The canonical Data object stores data.x as a 2-D tensor [N, D]. If your node features are images [N, C, H, W] or volumes [N, C, D, H, W], PyG's built-in layers expect them flattened to [N, C*H*W]. This destroys the spatial structure that convolutional layers would otherwise leverage. Researchers working with image patches as graph nodes, volumetric sensor data, or any structured multi-dimensional node features face this limitation.

Edge features have similar constraints. data.edge_attr is also expected to be [E, D]. Structured edge features (e.g., pair-wise image comparisons, volumetric edge representations) require manual handling or custom layer implementations.

Heterogeneous graph APIs are evolving. PyG's HeteroData API has changed substantially across versions. Code written for PyG 1.x often requires non-trivial migration for PyG 2.x. This is a genuine maintenance cost for long-running research projects.

Knowledge graph coverage is limited. PyG has a KGEModel interface and some KG dataset loaders, but the depth of supported KGE architectures (RotatE, ComplEx, DistMult with filtered ranking, multimodal entity features) is shallower than dedicated KGE libraries like PyKEEN. See TGraphX vs PyKEEN for a comparison of KGE tooling.

No built-in graph mining. PyG does not include centrality measures, motif counting, WL feature extraction, graph similarity, or classical graph algorithms. These require adding NetworkX or a custom implementation. See TGraphX vs NetworkX comparison for the analytics vs learning distinction.

No built-in graph generation, evolutionary optimization, or graph RL. These areas are outside PyG's scope. Generating random graphs with node features, evolutionary graph structure search, and training RL agents on graph environments all require external tools.

Reproducibility tooling is not built in. PyG does not provide a set_seed utility, deterministic mode wrapper, or reproducibility report. Researchers must wire this up manually. See GNN research reproducibility with TGraphX for what a complete reproducibility workflow requires.

---

The Flat Feature Assumption: A Deeper Look

The flat [N, D] feature assumption is worth examining carefully because it has practical consequences that are easy to miss.

When you flatten [N, C, H, W] to [N, C*H*W] to fit PyG's interface, three things happen:

1. Spatial locality is destroyed. A linear layer applied to the flattened vector treats each pixel equally — there is no notion of spatial neighbors within the feature map. If the spatial structure of your node features matters (e.g., image patches where neighboring pixels are correlated), you lose this on the first layer.

2. Parameter count explodes. A feature map of [C=16, H=32, W=32] has D = 16*32*32 = 16384 dimensions. A GCN layer GCNConv(16384, 256) requires ~4M parameters for a single weight matrix. The equivalent TensorGINLayer(in_channels=16, out_channels=256, spatial_rank=2) uses a 1×1 convolution with ~4K parameters.

3. Message passing is applied after flattening. The resulting aggregation operates on flattened vectors, making it impossible to apply spatial operations after aggregation.

This is not a criticism of PyG per se — its design goals are general graph learning with vector features. But it is a real constraint that researchers working with naturally spatial data should understand before committing to a design.

---

When PyG Is the Right Choice

Despite its limitations, PyG is the right tool in many common research scenarios:

• You are reproducing a published PyG baseline, and staying within the same library avoids version-mismatch bugs.
• Your node features are naturally vectorial (citation network bag-of-words, molecular fingerprints, protein sequence embeddings).
• You need a specific GNN layer that is implemented in PyG but not elsewhere.
• You need OGB evaluator integration for leaderboard submission.
• You are doing link prediction on standard citation or knowledge graph benchmarks where PyG's samplers are well-tested.

See TGraphX vs PyTorch Geometric and TGraphX vs PyTorch Geometric: Advanced Comparison for a detailed feature-by-feature breakdown.

---

Comparison Table: PyG vs TGraphX Feature Coverage

---

Common Misconceptions

"PyG is faster than everything else." PyG's C++/Rust scatter kernels are fast, but speed depends heavily on graph size, batch size, hardware, and layer type. No comparison article here provides benchmark numbers — see TGraphX benchmark disclaimers for why benchmark comparisons require careful experimental design.

"PyG is the reference implementation of GNN research." Several important architectures (GIN, GCNII, DeeperGCN) appeared in code before or alongside their PyG integrations. PyG's implementation of a layer may differ in normalization, initialization, or default hyperparameters from the original authors' code.

"If PyG doesn't support it, you need to build from scratch." PyG and other libraries (TGraphX, DGL, NetworkX) can coexist in one pipeline. The TGraphX + PyG complementary workflow article describes how to use each for the tasks it handles best.

---

Honest Summary

PyG is a mature, well-documented, widely used GNN library. Its dataset coverage, layer library, and community make it the natural starting point for most GNN research with standard vector node features.

Its limitations — flat feature constraint, heterogeneous API evolution, absent graph mining and RL tooling, limited reproducibility infrastructure — are real and matter for specific research workflows. Knowing these in advance prevents architectural decisions that are expensive to reverse.

For spatial, volumetric, or structured node features; for combined graph learning and mining; for reproducibility-first workflows; or for graph generation and RL, you will likely need to supplement or replace PyG. The choice should be based on your actual feature representation and workflow requirements, not on any library's marketing.

---

Further Reading

• Shape-aware validation in TGraphX — why shape errors are subtle and how to catch them
• Flat vector node features: why they are insufficient — the spatial structure argument in depth
• GNN research reproducibility — what a reproducible workflow requires beyond a random seed
• TGraphX benchmark disclaimers — how to read performance comparisons honestly
• Graph learning research integrity and benchmarks — broader context on GNN evaluation