torch-cluster is deprecated, and pyg-lib is where these algorithms went

The deprecation notice is the first thing in the README

The README opens with a caution block that says the repository is deprecated in favour of pyg-lib 0.7.0 or newer. Everything else in the documentation describes a package that is no longer the recommended home for these algorithms.

That changes how the rest of this should be read. torch-cluster is a small extension library of optimised graph cluster algorithms for use in PyTorch, and it contains a specific set of operations. Graclus, from Dhillon and colleagues. Voxel grid pooling, from work by Simonovsky and Komodakis. Iterative farthest point sampling, from the PointNet++ line of work. k-NN and radius graph generation, clustering based on nearest points, and random walk sampling from the node2vec paper. The README states that all included operations work on varying data types and are implemented for both CPU and GPU.

Those algorithms are still the algorithms people want. The point of the deprecation notice is where the maintained implementation lives now. For a new project the decision is made for you, and for an existing project it is a migration you have to schedule rather than a package you install freely.

The licence is MIT, and the code lives in a repository with a csrc directory of C++ and CUDA sources, a torch_cluster Python package, a CMakeLists.txt, a setup.py that wires the extension build, and a test directory.

Graclus picks an unmarked vertex and matches it to its heaviest unmarked neighbour

Graclus is the canonical operation here, so it is worth reading closely, because the shape of the call tells you how the library expects its data.

The README describes it as a greedy clustering algorithm of picking an unmarked vertex and matching it with one of its unmarked neighbours, choosing the neighbour that maximises the edge weight. The GPU version is adapted from work by Fagginger, Auer and Bisseling on a GPU algorithm for greedy graph matching.

The inputs are an edge list in coordinate form rather than an adjacency matrix: a row tensor and a column tensor of endpoint indices, and an optional weight tensor.

import torch
from torch_cluster import graclus_cluster

row = torch.tensor([0, 1, 1, 2])
col = torch.tensor([1, 0, 2, 1])
weight = torch.tensor([1., 1., 1., 1.])  # Optional edge weights.

cluster = graclus_cluster(row, col, weight)

The result is a cluster assignment per vertex, and the README shows what that looks like for that input.

print(cluster)
tensor([0, 0, 1])

So the two vertices 0 and 1 end up in one cluster and vertex 2 in another, which is what greedy matching on that three-edge graph produces. The edge list convention matters if you are coming from a library that expects a dense adjacency matrix, and it is the same convention used across the other operations in the package.

Voxel grid pooling and farthest point sampling for point clouds

The point-cloud side of the library covers two different needs. Voxel grid pooling overlays a regular grid of user-defined size over a point cloud and clusters all points that fall within the same voxel. The call takes the positions tensor and a size tensor describing the grid.

import torch
from torch_cluster import grid_cluster
: 
pos = torch.tensor([[0., 0.], [11., 9.], [2., 8.], [2., 2.], [8., 3.]])
size = torch.Tensor([5, 5])

cluster = grid_cluster(pos, size)

The README prints the resulting cluster assignment for those five points as tensor([0, 5, 3, 0, 1]). Note the cluster identifiers are not contiguous, they follow the grid cell numbering, which is worth knowing if you intend to use them as indices into a pooled feature tensor without remapping them.

Farthest point sampling is the other one, described as a sampling algorithm that iteratively samples the most distant point with regard to the rest. It works on a position tensor plus a batch tensor, so a single call can sample across several point clouds at once, with a ratio argument and a random_start flag.

Both of these exist because the underlying operations are loops that are awkward and slow in Python, which is the whole reason for the extension library. In a normal PyTorch Geometric stack, torch-cluster is the package that provides them, and pyg-lib is where the maintainer moved them.

Wheels are published per PyTorch and CUDA combination

Installation is a pip install with an index URL that names your exact PyTorch version and CUDA build, because the compiled extension has to match the ABI of the PyTorch it links against.

pip install torch-cluster -f https://data.pyg.org/whl/torch-2.11.0+${CUDA}.html

The ${CUDA} placeholder is replaced by cpu, cu126, cu128 or cu130 depending on the PyTorch installation you are targeting. The README documents the same command for PyTorch 2.11, 2.10 and 2.9, each with a table of supported platforms: Linux and Windows are covered for the CPU and CUDA builds, while macOS is listed for the CPU build only.

Older PyTorch versions are covered as well. The README lists binaries going back to PyTorch 1.4.0 and forward through 2.8.0, following the same procedure. The catch for old versions is that you have to name the latest supported version explicitly, or install with pip install --no-index, so that pip does not fall back to building the package from source by mistake.

For a maintainer of a pinned environment, that list of version to wheel combinations is the useful part of this page. It tells you which combinations exist and which do not, and the macOS row tells you that a CUDA build of this package was never published for Apple hardware.

Building from source, and the CUDA architecture list trap in containers

The source path is documented for anyone who needs a combination without a wheel. The requirements are that at least PyTorch 1.4.0 is installed and that cuda/bin and cuda/include are on your PATH and CPATH respectively, which the README checks with the version of torch and the two environment variables.

With that in place, the build is a normal pip install of the package.

pip install torch-cluster

There is one container-specific failure mode documented. In a Docker container without an NVIDIA driver, PyTorch needs to evaluate the compute capabilities and may fail, and the fix is to set them explicitly through TORCH_CUDA_ARCH_LIST.

export TORCH_CUDA_ARCH_LIST = "6.0 6.1 7.2+PTX 7.5+PTX"

The build itself is driven by setup.py, which globs the C++ sources in csrc, pairs each with the CPU and CUDA suffixes depending on what is available, and adds an OpenMP define when the parallel_info output reports OpenMP support and the platform is not macOS. The same file honours FORCE_CUDA, FORCE_ONLY_CUDA and FORCE_ONLY_CPU environment variables, so you can force which variants get compiled regardless of what the local machine reports.

What the successor looks like from this repository's point of view

The alternative to torch-cluster is pyg-lib, and the difference in approach is one of packaging and ownership rather than algorithms. The deprecation notice points at pyg-lib 0.7.0 or newer as the place to go, and the package list here is exactly the kind of low-level graph operation set that a shared extension library for the PyTorch Geometric ecosystem provides.

There is a second difference worth noting. torch-cluster is a standalone package with its own wheels, its own PyTorch version matrix and its own build flags, so it ages in lockstep with PyTorch releases. A shared library inside the ecosystem is versioned alongside the rest of the stack, so the number of things you have to keep in step is smaller.

The practical alternative for someone who does not want to migrate at all is to stop depending on the compiled extension and express the same operations in PyTorch itself. For nearest-neighbour graph construction and voxel pooling that is feasible, since both are tensor operations, but for Graclus and farthest point sampling it means writing the greedy loop yourself, which is the part torch-cluster existed to avoid. That is a reasonable trade for a research script and a poor one for a training pipeline.

If you are already on pyg-lib, nothing here needs changing. If you are still on torch-cluster, the migration path is named in the README and the version floor is stated as 0.7.0.

Editorial conclusion

torch-cluster belongs in an existing environment that already pins it and has no migration scheduled, and nowhere else. New work should start with pyg-lib 0.7.0 or newer, which the README names as the successor and which already covers the same graph operations. Before you plan a move, check which PyTorch and CUDA combination your project targets, because the published wheels are per combination and the source build path depends on cuda/bin and cuda/include being on your PATH and CPATH.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. rusty1s/pytorch_cluster on GitHub