Remove deprecated torch-cluster in favor of pyg-lib (#10682)

Part of #10684.

Author: akihironitta

.github/CONTRIBUTING.md

@@ -23,11 +23,11 @@ To develop PyG on your machine, here are some tips:
    print(torch.__version__)
    ```
 
-1. *(Optional)* Follow the [installation instructions](https://github.com/pyg-team/pytorch_geometric#installation) to install `pyg-lib`, `torch-scatter`, `torch-sparse`, and `torch-cluster` (if you haven't already).
+1. *(Optional)* Follow the [installation instructions](https://github.com/pyg-team/pytorch_geometric#installation) to install `pyg-lib`, `torch-scatter`, and `torch-sparse` (if you haven't already).
    Note that this step is optional and only necessary if you develop a feature that uses one of these libraries.
 
    ```bash
-   pip install pyg-lib torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
+   pip install pyg-lib torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
    ```
 
    where `${TORCH}` should be replaced by your PyTorch version (*e.g.*, `2.8.0`), and `${CUDA}` should be replaced by your CUDA version (*e.g.*, `cpu`, `cu126`, `cu128`, or `cu129`).
@@ -68,7 +68,7 @@ To develop PyG on your machine, here are some tips:
    pytest
    ```
 
-   In case an error occurs, please first check if all sub-packages ([`pyg-lib`](https://github.com/pyg-team/pyg-lib), [`torch-scatter`](https://github.com/rusty1s/pytorch_scatter), [`torch-sparse`](https://github.com/rusty1s/pytorch_sparse) and [`torch-cluster`](https://github.com/rusty1s/pytorch_cluster)) are on its latest reported version.
+   In case an error occurs, please first check if all sub-packages ([`pyg-lib`](https://github.com/pyg-team/pyg-lib), [`torch-scatter`](https://github.com/rusty1s/pytorch_scatter), and [`torch-sparse`](https://github.com/rusty1s/pytorch_sparse)) are on its latest reported version.
 
 1. Install pre-commit hooks:
 

.github/actions/setup/action.yml

@@ -102,5 +102,5 @@ runs:
         UV_INDEX_STRATEGY: unsafe-best-match
       run: |
         uv pip install scipy
-        uv pip install --no-index --upgrade torch-scatter torch-sparse torch-cluster -f https://data.pyg.org/whl/torch-${{ inputs.torch-version }}+${{ inputs.cuda-version }}.html
+        uv pip install --no-index --upgrade torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-${{ inputs.torch-version }}+${{ inputs.cuda-version }}.html
       shell: bash

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Deprecated
 
+- Deprecated support for `torch-cluster` in favor of `pyg-lib>=0.6.0` ([#10682](https://github.com/pyg-team/pytorch_geometric/pull/10682))
 - Deprecated support for `torch-spline-conv` in favor of `pyg-lib>=0.6.0` ([#10622](https://github.com/pyg-team/pytorch_geometric/pull/10622))
 
 ### Removed

README.md

@@ -354,10 +354,9 @@ pip install torch_geometric
 
 If you want to utilize the full set of features from PyG, there exists several additional libraries you may want to install:
 
-- **[`pyg-lib`](https://github.com/pyg-team/pyg-lib)**: Heterogeneous GNN operators, graph sampling routines, and [`SplineConv`](https://pytorch-geometric.readthedocs.io/en/latest/generated/torch_geometric.nn.conv.SplineConv.html) support
+- **[`pyg-lib`](https://github.com/pyg-team/pyg-lib)**: Heterogeneous GNN operators, graph sampling routines, graph clustering routines, and [`SplineConv`](https://pytorch-geometric.readthedocs.io/en/latest/generated/torch_geometric.nn.conv.SplineConv.html) support
 - **[`torch-scatter`](https://github.com/rusty1s/pytorch_scatter)**: Accelerated and efficient sparse reductions
 - **[`torch-sparse`](https://github.com/rusty1s/pytorch_sparse)**: [`SparseTensor`](https://pytorch-geometric.readthedocs.io/en/latest/advanced/sparse_tensor.html) support
-- **[`torch-cluster`](https://github.com/rusty1s/pytorch_cluster)**: Graph clustering routines
 
 These packages come with their own CPU and GPU kernel implementations based on the [PyTorch C++/CUDA/hip(ROCm) extension interface](https://github.com/pytorch/extension-cpp).
 For a basic usage of PyG, these dependencies are **fully optional**.
@@ -370,7 +369,7 @@ For ease of installation of these extensions, we provide `pip` wheels for all ma
 To install the binaries for PyTorch 2.11, simply run
 
 ```
-pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.11.0+${CUDA}.html
+pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.11.0+${CUDA}.html
 ```
 
 where `${CUDA}` should be replaced by either `cpu`, `cu126`, `cu128`, or `cu130` depending on your PyTorch installation.
@@ -386,7 +385,7 @@ where `${CUDA}` should be replaced by either `cpu`, `cu126`, `cu128`, or `cu130`
 To install the binaries for PyTorch 2.10, simply run
 
 ```
-pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.10.0+${CUDA}.html
+pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.10.0+${CUDA}.html
 ```
 
 where `${CUDA}` should be replaced by either `cpu`, `cu126`, `cu128`, or `cu130` depending on your PyTorch installation.
@@ -402,7 +401,7 @@ where `${CUDA}` should be replaced by either `cpu`, `cu126`, `cu128`, or `cu130`
 To install the binaries for PyTorch 2.9, simply run
 
 ```
-pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.9.0+${CUDA}.html
+pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.9.0+${CUDA}.html
 ```
 
 where `${CUDA}` should be replaced by either `cpu`, `cu126`, `cu128`, or `cu130` depending on your PyTorch installation.

docker/Dockerfile.xpu

@@ -27,5 +27,5 @@ RUN echo "source /opt/intel/oneapi/setvars.sh --force" >> /root/.bashrc
 
 # Install PyG
 RUN pip install ninja wheel ogb && pip install git+https://github.com/pyg-team/pyg-lib.git && \
-    pip install torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.5.0+cpu.html && \
+    pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.5.0+cpu.html && \
     pip install torch_geometric

docs/source/install/installation.rst

@@ -28,14 +28,13 @@ Additional Libraries
 
 If you want to utilize the full set of features from :pyg:`PyG`, there exists several additional libraries you may want to install:
 
-* `pyg-lib <https://github.com/pyg-team/pyg-lib>`__: Heterogeneous GNN operators, graph sampling routines, and :class:`~torch_geometric.nn.conv.SplineConv` support
+* `pyg-lib <https://github.com/pyg-team/pyg-lib>`__: Heterogeneous GNN operators, graph sampling routines, graph clustering routines, and :class:`~torch_geometric.nn.conv.SplineConv` support
 * `torch-scatter <https://github.com/rusty1s/pytorch_scatter>`__: Accelerated and efficient sparse reductions
 * `torch-sparse <https://github.com/rusty1s/pytorch_sparse>`__: :class:`SparseTensor` support, see `here <https://pytorch-geometric.readthedocs.io/en/latest/advanced/sparse_tensor.html>`__
-* `torch-cluster <https://github.com/rusty1s/pytorch_cluster>`__: Graph clustering routines
 
 .. note::
-   ``torch-spline-conv`` is no longer required as a separate package.
-   Its functionality has been migrated to ``pyg-lib>=0.6.0``.
+   ``torch-cluster`` and ``torch-spline-conv`` are no longer required as separate packages.
+   Their functionality has been migrated to ``pyg-lib>=0.6.0``.
 
 These packages come with their own CPU and GPU kernel implementations based on the :pytorch:`null` `PyTorch C++/CUDA/hip(ROCm) extension interface <https://github.com/pytorch/extension-cpp/>`_.
 For a basic usage of :pyg:`PyG`, these dependencies are **fully optional**.
@@ -64,7 +63,7 @@ For ease of installation of these extensions, we provide :obj:`pip` wheels for t
 
    .. code-block:: none
 
-      pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
+      pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
 
    where :obj:`${TORCH}` and :obj:`${CUDA}` should be replaced by the specific :pytorch:`PyTorch` and CUDA versions, respectively:
 
@@ -86,13 +85,13 @@ For ease of installation of these extensions, we provide :obj:`pip` wheels for t
 
    .. code-block:: none
 
-      pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.11.0+cu130.html
+      pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.11.0+cu130.html
 
    For example, for :pytorch:`PyTorch` 2.10.* and CUDA 12.8, type:
 
    .. code-block:: none
 
-      pip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/torch-2.10.0+cu128.html
+      pip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.10.0+cu128.html
 
 **Note:** Binaries of older versions are also provided for :pytorch:`PyTorch` 1.4.0, 1.5.0, 1.6.0, 1.7.0/1.7.1, 1.8.0/1.8.1, 1.9.0, 1.10.0/1.10.1/1.10.2, 1.11.0, 1.12.0/1.12.1, 1.13.0/1.13.1, 2.0.0/2.0.1, 2.1.0/2.1.1/2.1.2, 2.2.0/2.2.1/2.2.2, 2.3.0/2.3.1, 2.4.0/2.4.1, 2.5.0/2.5.1, 2.6.0, 2.7.0/2.7.1, and 2.8.0 (following the same procedure).
 **For older versions, you need to explicitly specify the latest supported version number** or install via :obj:`pip install --no-index` in order to prevent a manual installation from source.
@@ -163,7 +162,6 @@ In case a specific version is not supported by `our wheels <https://data.pyg.org
       pip install --verbose git+https://github.com/pyg-team/pyg-lib.git
       pip install --verbose torch_scatter
       pip install --verbose torch_sparse
-      pip install --verbose torch_cluster
 
 In rare cases, CUDA or :python:`Python` path problems can prevent a successful installation.
 :obj:`pip` may even signal a successful installation, but execution simply crashes with :obj:`Segmentation fault (core dumped)`.

docs/source/install/quick-start.html

@@ -130,7 +130,7 @@
     }
 
     else {
-      $("#command pre").text(`pip install torch_geometric\n\n# Optional dependencies:\npip install pyg_lib torch_scatter torch_sparse torch_cluster -f https://data.pyg.org/whl/${$("#command").attr("torch")}+${$("#command").attr("cuda")}.html`);
+      $("#command pre").text(`pip install torch_geometric\n\n# Optional dependencies:\npip install pyg_lib torch_scatter torch_sparse -f https://data.pyg.org/whl/${$("#command").attr("torch")}+${$("#command").attr("cuda")}.html`);
     }
   }
 

examples/datapipe.py

@@ -50,11 +50,11 @@ class MeshOpener(IterDataPipe):
     def __init__(self, dp: IterDataPipe) -> None:
         try:
             import meshio  # noqa: F401
-            import torch_cluster  # noqa: F401
+            import pyg_lib  # noqa: F401
         except ImportError as e:
             raise ImportError(
                 "To run this example, please install required packages:\n"
-                "pip install meshio torch-cluster") from e
+                "pip install meshio pyg-lib") from e
 
         super().__init__()
         self.dp = dp

examples/mnist_graclus.py

@@ -13,12 +13,10 @@
     max_pool,
     max_pool_x,
 )
-from torch_geometric.typing import WITH_SPLINE, WITH_TORCH_CLUSTER
+from torch_geometric.typing import WITH_PYG_LIB, WITH_SPLINE
 from torch_geometric.utils import normalized_cut
 
-if not WITH_TORCH_CLUSTER:
-    quit("This example requires 'torch-cluster'")
-if not WITH_SPLINE:
+if not WITH_PYG_LIB or not WITH_SPLINE:
     quit("This example requires 'pyg-lib>=0.6.0'")
 
 path = osp.join(osp.dirname(osp.realpath(__file__)), '..', 'data', 'MNIST')

examples/mnist_nn_conv.py

@@ -14,11 +14,11 @@
     max_pool,
     max_pool_x,
 )
-from torch_geometric.typing import WITH_TORCH_CLUSTER
+from torch_geometric.typing import WITH_PYG_LIB
 from torch_geometric.utils import normalized_cut
 
-if not WITH_TORCH_CLUSTER:
-    quit("This example requires 'torch-cluster'")
+if not WITH_PYG_LIB:
+    quit("This example requires 'pyg-lib>=0.6.0'")
 
 path = osp.join(osp.dirname(osp.realpath(__file__)), '..', 'data', 'MNIST')
 transform = T.Cartesian(cat=False)