📚 课程目录第2章环境搭建

2. 环境搭建：安装leidenalg 和 igraph，验证安装

说实话，很多搞聚类的朋友上来就调参，结果跑出来的图乱七八糟。

后来一查，好家伙——连算法库都没装对版本。

这一节，咱们先把地基打牢。我呢，就按自己踩过的坑来给你讲。

2.1 为什么要用两个库？

Leiden 算法本身是 igraph 的社区检测方法之一，但最原汁原味的实现藏在 leidenalg 这个包里。而 leidenalg 又依赖 igraph 的数据结构。说白了，你需要两个轮子：

igraph：负责图结构、邻接矩阵、属性管理。它是骨架。
leidenalg：负责调算法的核心——优化模块度、分区、层次化聚类。它是引擎。

这两个库的版本必须严格匹配。我曾经试过 igraph 0.10 配 leidenalg 0.8，直接报 AttributeError。后来才搞明白，它们之间有个隐形的“版本锁”。

2.2 安装方式一览

我个人习惯用 conda 管理 Python 环境，省去编译的麻烦。pip 也能装，但某些系统（尤其是 Windows）下 leidenalg 需要 C++ 编译环境，容易翻车。

安装方式	命令	适合场景
conda (推荐)	`conda install -c conda-forge python-igraph leidenalg`	Linux / macOS / Windows，避免编译问题
pip + 二进制轮子	`pip install python-igraph leidenalg`	macOS / Linux，Python 3.8–3.11 常见
从源码编译	`pip install python-igraph --no-binary=python-igraph`	需要自定义编译选项或特殊架构

⚠ 避坑提示：
Windows 用户用 pip 安装 leidenalg 时，如果提示 Microsoft Visual C++ 14.0 is required，别硬刚。直接切到 conda-forge 渠道，省心省力。

2.3 一步步搭建环境

我先把关键步骤拆开讲。你跟着做就行。

2.3.1 创建专用虚拟环境

避免污染系统的 Python，我总喜欢另起一个环境，取名就叫 leiden_lab。

conda create -n leiden_lab python=3.10 -y
conda activate leiden_lab

Python 版本我推荐 3.10 或 3.11。3.12 虽然也能装，但某些 igraph 的 C 扩展包刚适配完，不够稳。我自己在 3.10 上跑过几百次，没出过问题。

2.3.2 安装 igraph + leidenalg

一条命令搞定依赖链：

conda install -c conda-forge python-igraph leidenalg

如果你非要用 pip，记得先升级 pip：

pip install --upgrade pip setuptools wheel
pip install python-igraph leidenalg

等安装完成后，验证一下是否都装上了。你想想看，这一步要是跳过，后面报错你都不知道缺了啥。

2.3.3 验证安装

在终端进入 Python 交互模式，或者写个 test.py。我一般就用交互模式，快：

python -c "import igraph; print('igraph version:', igraph.__version__)"
python -c "import leidenalg; print('leidenalg version:', leidenalg.__version__)"

理想的输出长这样：

igraph version: 0.11.6
leidenalg version: 0.10.6

如果你看到类似 ModuleNotFoundError，那就说明环境没对上，或 pip 装到了全局环境。我会先检查当前在用哪个 Python：

which python
python -c "import sys; print(sys.executable)"

  ✅ 快速自查表

  确认 conda 或 pip 的 Python 版本 ≥ 3.8
确认 igraph 版本 ≥ 0.9.0（leidenalg 要求）
两个库在同一环境里，不要混用 conda 和 pip 的 igraph

2.4 跑个小测试：确认 API 能跑通

光看版本号不够，我习惯再跑一段真正的聚类代码。下面是经典的小世界网络测试：

import igraph as ig
import leidenalg

# 创建一个小世界图（10个节点，每个节点连3个邻居，重连概率0.1）
g = ig.Graph.Watts_Strogatz(1, 10, 3, 0.1)

# 用 Leiden 优化模块度
partition = leidenalg.find_partition(
    g, leidenalg.ModularityVertexPartition
)

print("分区数量:", len(partition))
print("每个节点归属社区:", partition.membership)

如果输出类似：

分区数量: 2
每个节点归属社区: [0, 0, 0, 1, 1, 1, 0, 0, 1, 1]

恭喜你，环境完全打通了。代码里的 ModularityVertexPartition 是默认的优化目标函数，后面章节我们会换成其他目标函数（CPM、RB等），到时候细节再说。

2.5 整章知识体系

下面这张图把环境搭建和接下来实验的关系捋了一遍。你可以把它当作本章的“导航地图”。

💡 小技巧： 如果你用的是 Jupyter Notebook，建议在第一个 cell 里执行版本检查。我习惯写成：

import igraph as ig, leidenalg
print(f"igraph {ig.__version__}, leidenalg {leidenalg.__version__}")
print("Test partition:", leidenalg.find_partition(ig.Graph.Full(4), leidenalg.ModularityVertexPartition).membership)

这样一步到位，不用切来切去。

2.6 常见问题与我的翻车经历

ImportError: cannot import name 'VertexPartition' – 我遇到过好几次，都是 igraph 版本太老。升级到 0.10 以上就解决了。
leidenalg 安装后无法 import – 多半是 C 扩展没编译成功。我建议直接用 conda，或者换 Linux 系统。
igraph 和 leidenalg 版本锁死了 – 有个隐藏规则：leidenalg 0.9.x 只能用 igraph 0.10.x，leidenalg 0.10.x 才能用 igraph 0.11.x。跳版本就会挂。

嗯，这里要注意——千万不要同时通过 conda 和 pip 各装一半。我当初傻过，以为两个渠道能互补，结果 igraph 是 conda 的，leidenalg 是 pip 的，底层 C 库冲突，连 segfault 都蹦出来了。实践告诉我：老实统一渠道，一条路走到黑。

2.7 小结

环境搭建听起来基础，但你不花十分钟检查，后面几小时都白费。我通常在项目开始前，写一个 check_env.py，放到 repo 根目录，新人拉下来就跑一遍。你也可以照做。

现在，你手边的 Python 环境已经能从图里切出社区了。下一个问题是：那些参数到底在控制什么？别急，第三章我们就会钻进 leidenalg.find_partition 的参数表里，一个一个揪出来看。