software

Conda 使用技巧(四):环境配好后怎么保存?从 environment.yml 到复现验收

作者:发布于 2026-11-20更新于 2026-11-16约 11 分钟阅读
保存环境,需要三层材料:说明需求、记录现状、验证行为。

经过前三篇,你已经能创建环境、安装 Biopython,并处理常见的运行错误。接下来会出现一个更实际的问题:换一台电脑、交给同事,或者半年以后再做一遍,怎样知道自己使用的还是那套软件?只写一句“需要 Python 和 Biopython”,通常无法解释版本、渠道和平台之间的差异。

这一篇继续使用两条序列的统计项目,把环境记录拆成三个层次:表达项目需要什么,记录这次实际装了什么,验证重建以后做出了什么。三层一起保存,才能避免“文件都交了,同事还是跑不通”的情况。我们追求的是可解释、可核对的复现过程,不把一份导出文件夸大成跨平台万能备份。

第四篇示意:项目需求、实际安装与结果验收三层保存

一、先写一份人能够读懂的需求清单

在项目目录新建 environment.yml,内容如下。YAML 使用空格缩进,不能把缩进随意改成制表符。环境名称、渠道与依赖各占一个明确位置,读者不需要猜哪些软件是项目直接用到的。

name: conda-lab
channels:
  - conda-forge
  - nodefaults
dependencies:
  - python=3.11
  - biopython=1.85
  - pip

这里的 nodefaults 是特殊设置,用于避免在这个环境文件的求解中额外加入默认渠道,不是一个真实下载仓库。核心版本保持与前文一致,pip 被列出是为了能够进行相应检查。没有使用 pip 安装额外包,就不用为了显得完整而添加虚构的 pip 依赖段。

这份清单表达了直接需求,但 Python 3.11 下面具体选哪个补丁版本、底层库选择哪个构建,仍可能随时间与平台变化。精简清单便于理解和维护,却不等于逐个软件包都被完全锁定。相关环境文件行为见 Conda 环境管理文档。

如果项目实际用过更多依赖,应在这里如实补齐。尤其是执行脚本时临时调用的外部命令,不能因为它不出现在 Python 的 import 语句中就忘记记录。数据库、参考基因组和模型权重则需要单独记录,它们不一定属于 Conda 管理的软件包。

二、导出文件之前,先明确接收者需要什么

面对同事交接,常见需求有两种:一种是让对方看懂项目需要哪些软件,另一种是尽可能保留当前机器安装状态。它们适合不同粒度的文件。下面在项目目录执行导出,先保留原始文件,再检查内容,不要立刻发送到公共仓库。

conda env export -n conda-lab --from-history > environment-history.yml
conda env export -n conda-lab --no-builds > environment-resolved.yml
conda list -n conda-lab --explicit > explicit-platform.txt

第一份主要体现显式请求的 Conda 依赖,便于表达安装意图,但不要假设它完整包含所有额外 pip 安装情况。第二份记录更完整的软件版本并去掉构建字符串,通常仍带有平台相关依赖。第三份记录精确包来源,适合相同平台的重建路径,但仍需要能够获取相应包文件。导出选项见 conda env export 与 conda list。

保存方式 主要用途 不能据此保证的事
手写精简 YAML 描述项目直接需求 每个底层包完全不变
历史需求导出 回顾显式安装请求 收齐所有外部软件与数据
完整版本导出 排查实际依赖差异 跨系统无条件重建
explicit 文件 同平台精确指定包 包永远可下载、任意平台可用
小样例与期望结果 验证项目行为 完整科研结论自动复现

导出后要检查是否存在本机 prefix 路径、用户名、内部渠道地址或认证信息。公开分享的环境说明不应带入这些内容。精简清单可以保留必要的公开渠道,移除仅属于自己电脑的绝对安装位置;原始导出则留作内部排查依据。删掉路径不等于解决了所有可移植性问题,仍然需要下一步实际重建。

新版 Conda 还提供更统一的 conda export 命令和格式选项,旧环境未必具备相同接口。本系列保留广泛使用的传统导出形式,避免读者为了学一个例子就先升级管理工具。需要新接口时先检查本机帮助,并对照 conda export 官方文档,不要混淆不同版本支持的参数。

三、用新名字重建,才能检验文件有没有漏东西

不要直接覆盖正在工作的 conda-lab。先在同一台机器上创建一个名为 conda-lab-copy 的新环境,从项目目录读取手写的 environment.yml。名字换了,原来的环境就可以保留用于对照。

conda env create -n conda-lab-copy -f environment.yml
conda run -n conda-lab-copy python -c "import sys, Bio; print(sys.executable); print(Bio.__version__)"
conda run -n conda-lab-copy python summarize_fasta.py demo.fa

成功创建只是第一道检查。还要确认解释器路径属于新环境,Biopython 版本符合清单,两个序列的统计结果与原环境一致。如果新环境运行失败,不要立刻从旧环境里随便复制文件补洞。先找出缺的是哪个依赖,把它补进说明,再重新验证,才能把隐含条件变成明确条件。

如果目标是同平台精确包重建,可以使用 explicit 文件创建另一个新环境。注意阅读文件头部的平台信息,并保留原始包渠道;跨 Linux、Windows、macOS 或处理器架构时,不应直接假定这条路线可用。

conda create -n conda-lab-exact --file explicit-platform.txt
conda run -n conda-lab-exact python summarize_fasta.py demo.fa

这条命令针对 Conda 包记录,不会自动把项目文件、参考库和所有外部资源一起搬过去。若项目使用 pip 依赖,应额外记录和安装它们,再测试。不要把“环境创建成功”写成“论文完全复现成功”,前者只覆盖软件准备的一部分。

第四篇验收示意:新环境读同一输入,比较相同结果

四、把结果比较写成机器能够检查的一步

终端里滚动过的输出很容易丢失。可以分别在原环境和新环境运行,把统计结果保存在两个文件中。为了统一文本编码,下面保存过程由 Python 完成,不依赖不同 shell 的重定向编码规则。先把代码保存为 compare_envs.py,再从能够调用 Conda 的终端运行。

import subprocess
from pathlib import Path

outputs = []
for env in ("conda-lab", "conda-lab-copy"):
    result = subprocess.run(
        ["conda", "run", "-n", env, "python", "summarize_fasta.py", "demo.fa"],
        check=True, capture_output=True, text=True, encoding="utf-8"
    )
    text = result.stdout.strip().replace("\r\n", "\n") + "\n"
    Path(f"{env}.tsv").write_text(text, encoding="utf-8")
    outputs.append(text)
expected = "id\tlength\tgc_percent\nseq_A\t8\t50.00\nseq_B\t6\t66.67\n"
assert outputs[0] == outputs[1] == expected, "Result mismatch"
print("PASS: both environments match the expected result")
conda run -n conda-lab python compare_envs.py

比较时不仅检查两个环境是否相同,还检查是否等于手工推导的预期结果。否则两套环境产生了同样的错误输出,也可能被误判为通过。对本例这种确定性文本,严格比较很合适;涉及随机算法、并行计算和浮点误差时,则需要提前定义随机种子、数值容差与验收指标。

若系统中同时安装了多套 Conda,比较脚本里的 conda 应改成当前所用管理器的绝对路径。Windows 的命令入口形式也可能不同,本段自动比较脚本以 Linux 或 macOS 的 Conda 可执行文件入口为适用条件;Windows 读者可以先逐条运行前面的命令对照结果。第五篇会进一步把管理器位置写进启动程序。

五、交给同事的应该是一个小项目

一个可读的交付目录,至少包含环境说明、分析脚本、两条示例序列、预期输出和简短操作说明。说明里应写清在哪个目录执行、先运行哪条命令、成功后看到什么,以及哪些步骤属于可选检查。不要只发一张终端截图,让接收者自己猜缺失的文件名和执行顺序。

对真实生信项目,还应记录参考基因组版本、注释来源、数据预处理过程以及关键参数。如果这些东西发生变化,即使软件包完全一致,输出也可能不同。对于无法共享的原始数据,可以提供不含敏感信息的小样例,用来验证安装和输入输出格式,另行约定正式数据的交付方式。

环境文件也需要随着项目变更维护。某次增加依赖后,及时更新需求说明,并在新环境里重新跑样例;某次移除依赖后,检查脚本是否还有隐式调用。这样项目说明才能反映当前可运行状态,避免积累大量“以前可能用过”的包。

下一篇会把这些文件组织成一个可以反复启动的任务,显式设置环境、工作目录、日志和失败退出。若你需要把个人分析转成课题组可共享的运行方式,可以先整理当前项目的依赖与验收样例,再联系云生信咨询服务器环境方案。

下载全系列练习代码、示例数据与环境文件(ZIP;含操作说明与预期输出)

把知识用于当前任务

下一步可以直接开始分析

按研究目标查找在线工具、课程、计算资源或完整分析服务。

按目标找方案仍有疑问,联系客服 ↗