📚 课程目录第2章 Snakemake安装与环境配置

第2章 Snakemake 安装与环境配置

搭建一个干净、可复现的 Snakemake 环境，是所有质控流程的起点。这一关要是没走稳，后面调参数、跑批量、上集群全是坑。我见过太多人把包装得乱七八糟，最后 debug 的时间比写 Snakefile 还长。这一章咱们就把环境这件事彻底理清楚。

2.1 环境准备：Python 与 Conda

Snakemake 的本质是一个 Python 包，所以 Python 环境是它的根。我个人习惯用 Conda 来管理，不为别的，就图它能把 Python 版本、系统库、第三方依赖一次性锁死。你想想看，项目三个月后回来重跑，最怕的就是"哎呀当时用的哪个版本"——Conda 环境导出一下，全解决了。

先确认机器上有没有 Conda：

conda --version

如果没装，去 Miniconda 官网下载安装脚本，一路默认就行。我一般选 Miniconda 而不是 Anaconda，后者太臃肿，很多包我们用不上。

Python 版本方面，Snakemake 7.x 要求 Python ≥ 3.8，我推荐直接用 3.10。为什么？因为 3.8 已经进入维护末期，3.11 有些科学计算库还没完全适配，3.10 是当前最稳的平衡点。我在项目中踩过 Python 3.7 装不上新版 Snakemake 的坑——嗯，那次排查了一下午。

python --version

如果 Python 版本偏低，先用 Conda 升级：

conda install python=3.10

2.2 创建隔离的 Snakemake 环境

千万别在 base 环境里直接装 Snakemake。base 环境一旦乱了，整个 Conda 都可能崩。我一般给每个工具链单独开一个环境，命名规则是 工具名-用途，比如 snakemake-qc。这样清晰，也方便删了重建。

conda create -n snakemake-qc python=3.10 -y

创建完后激活：

conda activate snakemake-qc

激活后命令行前面会出现 (snakemake-qc)，说明你已经在隔离环境里了。这时候装任何包都不会影响系统 Python 或其他项目。

小窍门： 如果网络不太好，可以用 mamba 替代 conda，速度能快 5-10 倍。mamba 是 C++ 重写的依赖解析器，用法和 conda 几乎一样。

conda install mamba -c conda-forge -y
mamba create -n snakemake-qc python=3.10 -y

2.3 安装 Snakemake 核心及扩展

环境激活后，安装 Snakemake 核心包。最简单的做法是用 pip：

pip install snakemake

用 Conda 也可以，但我个人更倾向 pip，因为 Conda 的 bioconda 频道有时同步会慢几周，而 PyPI 上的版本通常是最新的。

有些高级功能需要额外安装扩展包。下面这个表格列出我常用的扩展，按需取用：

扩展包	安装方式	用途
reports	`pip install snakemake[reports]`	生成 HTML 格式的多维度质控报告
google-cloud	`pip install snakemake[google-cloud]`	对接 Google Cloud Storage
kubernetes	`pip install snakemake[kubernetes]`	在 K8s 集群上调度任务
messaging	`pip install snakemake[messaging]`	通过 Slack/邮件发送通知
all	`pip install snakemake[all]`	装上面所有扩展（不推荐，容易冲突）

刚开始做分类质控的话，只需要 core + reports 就够了。后续需要集群或云存储再补装。

pip install snakemake[reports]

2.4 验证安装与基础测试

装完别急着写流程，先做几个快速验证，确保环境没毛病。

第一步：检查版本

snakemake --version

正常会输出类似 7.32.4 这样的版本号。如果提示 command not found，说明环境没激活，或者 pip 安装路径没在 PATH 里。

第二步：查看帮助

snakemake --help

滚动输出一大段参数说明，看到就说明核心包安装成功。这时候可以检查一下关键参数列表里有没有 --cores、--snakefile、--config 这些选项。

第三步：写一个最小 Snakefile 做 dry-run

新建文件 Snakefile，内容如下：

rule all:
    input:
        "test.txt"

rule create_file:
    output:
        "test.txt"
    shell:
        "echo 'Snakemake is working' > {output}"

然后执行 dry-run（不实际运行，只检查 DAG）：

snakemake -n

输出应该显示 Job stats: 和 This was a dry-run。看到这些，说明解析和执行链路都没问题。

第四步：实际跑一次

snakemake --cores 1

运行结束后，用 cat test.txt 查看文件内容，确认输出正确。整个验证流程走完，环境才算真正就绪。

  验收清单：
  ☑ conda 环境激活后命令行前缀显示正确
☑ snakemake --version 输出版本号
☑ snakemake -n 能正确解析 Snakefile
☑ snakemake --cores 1 能成功生成目标文件

2.5 常见安装问题与避坑

安装过程中难免遇到各种幺蛾子。我把这些年碰到的典型问题列出来，你碰到类似情况可以直接翻到这里查。

问题 1： snakemake: command not found

原因： 环境未激活，或者 pip 安装到了系统 Python 而非 Conda 环境里。

解决： 先执行 conda activate snakemake-qc，然后用 which python 确认路径在 Conda env 下。如果不对，重新创建环境再装。

问题 2： 安装时报 ERROR: Could not find a version that satisfies the requirement snakemake

原因： Python 版本太低，或者 pip 源里没有对应版本。

解决： 升级 Python 到 3.10，或者用 pip install snakemake==7.32.4 指定一个已知稳定的版本。我曾经因为 Python 3.7 卡在这步一下午，后来发现官方早就停止支持了。

问题 3： snakemake -n 报错 NameError: name 'rule' is not defined

原因： Snakefile 语法错误，或者文件后缀名不对。Snakemake 默认读取 Snakefile 或 Snakefile.py，如果命名成 snakefile（小写 s）会找不到。

解决： 检查文件名首字母大写，同时确认内容没有拼写错误。可以用 snakemake --snakefile yourfile.smk 指定其他名字。

问题 4： 国内下载速度极慢，甚至超时中断

原因： PyPI 主站位于国外，国内访问不稳定。

解决： 配置国内镜像源，临时使用：

pip install snakemake -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置的话，在 ~/.pip/pip.conf 中加入：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

环境配好之后，你就可以放心地进入下一阶段——写 Snakefile 了。记住，一个干净的环境比任何奇技淫巧都管用。磨刀不误砍柴工，花 20 分钟把环境搭扎实，后续调参的时候你一定会感谢现在的自己。