Conda环境离线部署三种方案：整包迁移、本地源与目录裸拷

1. 先把离线部署这件事的边界划清楚Conda 环境离线部署这四个字说起来简单真正落在机房里就变成一堆让人头疼的细节。内网生产机、隔离测试区、工控现场、保密研发环境、客户机房这些地方共同的麻烦就是能拷文件但不能连接公网源。我在过去几年里大概有十几次要把一套本地能跑通的环境搬到没法联网的机器上最初几次都栽在同一个坑里我盯着conda install报的那行CondaHTTPError: Connection refused半天才反应过来问题不在网络配置而在我根本没想清楚包从哪里来。这篇内容写给三类人第一类是需要把本地开发环境迁移到隔离区的算法、数据同学第二类是需要在一批离线机器上批量搭建统一环境、还要长期可维护的运维同事第三类是刚接触 conda、正准备第一次做离线安装、想少走点弯路的入门者。我会把自己实际用过的三种方案完整拆开包括每种方案的适用场景、具体命令、参数为什么这么设、以及最后怎么验证这个环境是真的能用而不只是装上了。1.1 三种典型的无网络场景决定了不同的方案离线不是一种情况至少分三种选错方案等于白折腾。场景一一次性迁移环境之后不再变。典型是给现场演示机、评审机器装一套固定版本的推理环境装完就不动了。这种最适合整包迁移因为不用维护软件源一份压缩包拷过去解压就能用。场景二隔离区要长期迭代还要新建环境。比如某实验室的内网集群每周都可能新增依赖或者要按项目建不同的环境。这种就必须自建本地离线源否则你每次都得重新打包运维成本会失控。场景三原机器还在只是没法重装只能搬目录。有些旧设备上的环境是靠特殊编译选项手工凑出来的包源里根本没有一模一样的 build重新装一遍大概率失败。这种情况下只能硬拷贝整个环境目录再手工修路径。这三种场景对应我下面要讲的三个方案顺序也是我推荐的处理优先级能自建源就自建源临时迁移用整包实在不行才裸拷目录。1.2 先搞懂 conda 到底把东西放哪了很多人离线部署失败根子在于不清楚 conda 的文件布局。花两分钟理清后面所有报错你都能自己解释。conda 的安装目录下称前缀prefix里大致是这么几块路径作用离线迁移时要注意什么bin/Windows 是Scripts/可执行文件与入口脚本脚本首行的解释器路径是绝对路径换机器必须重写lib/python3.x/site-packages/Python 包实体一般可整体搬但含 .pth 文件指向旧路径的会失效conda-meta/*.json每个已安装包的元数据清单记录了包来源、文件列表、md5是校验环境的依据conda-meta/history安装历史迁移后追加记录便于追溯etc/conda/activate.d/激活时执行的钩子脚本极容易在打包时被忽略导致环境变量丢失全局pkgs/已下载的包缓存离线安装最重要的原料库别和 env 目录搞混关键区别envs/xxx是装好的环境pkgs/是下载下来的安装包缓存。离线安装本质上是先想办法把包弄进pkgs/再让 conda 不去联网找包。理解了这一层三种方案其实都是围绕这个思路的不同变形。1.3 三种方案横向对比先看结论再往下读维度方案一整包迁移方案二本地离线源方案三目录裸拷核心工具conda-packconda index--offlinersync 路径重写落地难度低中中高是否可新建环境否是否环境可迭代差好差跨机器兼容性中需同架构、glibc 足够好差路径与编译信息强绑定典型耗时打包 3~10 分钟首次准备 20~60 分钟拷贝时间取决于体积我的推荐度临时任务首选长期维护首选兜底手段有一点要提前说明三种方案都不解决跨 CPU 架构的问题。x86_64 上打出来的包搬到 ARM 机器上一定跑不起来这不是工具的问题是二进制不兼容。同理低版本 glibc 的机器跑不了在高版本 glibc 上编译的包报错通常是GLIBC_2.28 not found这类。这两条限制在下面所有方案里都成立不再重复。2. 方案一conda-pack 整包迁移五分钟能上手2.1 它到底做了什么以及不做什么conda-pack的思路很直接把指定环境里的所有文件打成一个压缩包同时改写掉里面指向旧前缀的绝对路径生成一个可搬迁的包。它并不是简单压缩关键在于它会把bin/下那些脚本的首行#!/old/prefix/bin/python改成相对可执行的形式还会生成一个conda-unpack脚本放在包里。所以正确的使用顺序是先解压到目标路径再执行conda-unpack。很多人解压完直接source activate然后报bad interpreter: No such file or directory就是因为跳过了这一步。它不做的事情也说清楚不处理 conda 之外的系统级依赖比如libGL.so.1、系统字体、显卡驱动不保证 pip 安装的带编译扩展的包一定能用不解决不同 glibc 版本的问题。2.2 打包端的操作与参数选择先保证打包机上这个环境是干净的、能跑的。我一般会先在源机上做一次快速自检conda activate myenv python -c import sys; print(sys.version) pip checkpip check会报出依赖冲突如果这里就有冲突打完包到对面一样是坏的先修好再打。然后装conda-pack并打包conda install -n base -c conda-forge conda-pack -y conda pack -n myenv \ -o /data/transfer/myenv.tar.gz \ --n-threads 4 \ --ignore-missing-files \ --ignore-editable-packages参数逐个说清楚--n-threads 4用多线程压缩环境大比如带了 PyTorch时能从几分钟降到一分钟内。线程数不要超过机器核数否则反而慢。--ignore-missing-files环境里如果有残留的、文件已被删掉的包记录不加这个会直接中断。这个参数我基本必加因为长期使用的环境里难免有手工删过文件的情况。--ignore-editable-packages如果环境里用pip install -e装过本地项目这些包的路径是链接到源码目录的打包必然失败。加了这个参数会跳过它们你需要自己把源码一起拷过去再装一遍。如果环境特别大还可以加--compress-level 1用一点体积换速度内网传输其实很快体积不是主要矛盾。还有一个容易被忽略的点打包前最好把 pip 缓存和__pycache__清一下能省不少体积。conda activate myenv find $CONDA_PREFIX -name __pycache__ -type d -prune -exec rm -rf {} pip cache purge打包完成后先看体积正常情况下压缩包相当于原环境的三分之一到二分之一。如果只有几百 KB说明你没打到正确的环境检查-n后面的名字。2.3 落地端的解包与修复流程目标机上的操作我一般固定写成一段脚本避免手抖set -e TARGET/opt/envs/myenv mkdir -p $TARGET tar -xzf /tmp/myenv.tar.gz -C $TARGET # 修复路径必须执行一次 $TARGET/bin/conda-unpack # 激活 source $TARGET/bin/activate python -c import sys; print(sys.prefix)conda-unpack这一步是关键。它做的事情包括把bin/下脚本里的 shebang 改成新的绝对路径、把.pth文件、sysconfig里记录的旧前缀替换掉、修正.dylib/.so里的 rpath部分场景。最后那行print(sys.prefix)是用来确认环境指向正确的输出应该是/opt/envs/myenv如果还是旧路径说明conda-unpack没执行成功或者你激活的是别的环境。Windows 目标机上的写法略有不同mkdir D:\envs\myenv tar -xzf D:\transfer\myenv.tar.gz -C D:\envs\myenv D:\envs\myenv\Scripts\conda-unpack.exe D:\envs\myenv\Scripts\activate.batWindows 上还要额外注意一点路径里不要有空格和中文。conda-unpack对Program Files这类带空格的路径处理不总是可靠我吃过一次亏最后把环境放到了D:\envs下面才正常。2.4 这个方案我踩过的三个坑坑一activate.d里的环境变量没了。有的包比如某些图形库、CUDA 相关包会在etc/conda/activate.d/放脚本设置LD_LIBRARY_PATH。conda-pack一般会带上这些文件但如果你的环境里是手工加的、没有对应包记录就不会被打进去。解决方式是在打包前把etc/conda/activate.d/整个目录单独拷一份落地后覆盖回去。坑二pip 装的包import报找不到顶层模块。这通常是easy-install.pth或__editable__文件还指向旧路径。补救办法是进环境后重新装一次那个包或者手工改.pthgrep -rl /old/prefix $CONDA_PREFIX/lib/python3.10/site-packages --include*.pth把查出来的文件里的旧路径改成新的。坑三包能解压但跑起来报libstdc.so.6: version GLIBCXX_3.4.29 not found。这不是 conda-pack 的问题是目标机的系统库太老环境里带的libstdc没被优先加载。临时解法是在激活后手动前置export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH长期方案还是升级目标机的基础库或者干脆用方案二在目标机同构的系统上准备包。3. 方案二自建本地离线 channel一次性投入长期受益3.1 思路把远程源变成一条 file:// 路径conda 的channels配置本质上是一堆 URL。既然https://...拉不到那就换成file:///opt/offline-channel让它从本地磁盘读。而 conda 读一个源只需要能看到两样东西包文件本身以及一份叫repodata.json的索引记录每个包的名字、版本、build、依赖、md5。所以方案二的全部工作可以拆成三步在有网的机器上把所有需要的包文件下载下来按linux-64、noarch这样的子目录摆放用conda index生成索引文件把整个目录拷到目标机配置channels指向本地路径安装时加--offline。这个方案最大的价值是可增量以后要新装一个包只要在联网机上补下载、重新 index、把新增文件拷过去目标机立刻就能用不需要重做整个环境。3.2 联网端怎么把包准确下载下来最直接的方式是把当前环境的精确清单导出来然后让 conda 只下载不安装。先导出显式清单这个清单包含每个包的完整 URL 和 md5conda list --explicit -n myenv /data/transfer/spec-explicit.txt内容大概长这样# This file may be used to create an environment using: # $ conda create --name env --file this file # platform: linux-64 EXPLICIT https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81 https://conda.anaconda.org/conda-forge/linux-64/libgcc-ng-13.2.0-h807b86a_3.conda#...有了这份清单就可以用--download-only让 conda 只把包拉到pkgs/目录不做链接conda create -p /data/stage/_tmp --download-only --file /data/transfer/spec-explicit.txt -y注意这里用-p指定一个临时前缀安装完成后直接删掉即可真正下载的东西在 conda 的pkgs_dirs里。如果你不确定pkgs_dirs在哪conda config --show pkgs_dirs下载完成后把pkgs/下所有的.conda和.tar.bz2文件按平台拷到 channel 目录里。这里有个细节文件名里带noarch的放noarch/其余放linux-64/或对应平台。批量分类脚本SRC$HOME/miniconda3/pkgs DST/data/offline-channel mkdir -p $DST/linux-64 $DST/noarch for f in $SRC/*.conda $SRC/*.tar.bz2; do [ -e $f ] || continue base$(basename $f) case $base in *noarch*) cp -n $f $DST/noarch/ ;; *) cp -n $f $DST/linux-64/ ;; esac donecp -n的作用是不覆盖已存在的文件重复执行不会出问题。3.3 生成索引这一步千万别跳index 没生成好conda 会直接报ChannelsNotFound或者PackagesNotFoundError很多人以为包拷过去了就行其实索引文件才是关键。conda install -n base -c conda-forge conda-index -y python -m conda_index /data/offline-channel旧一点的环境是用conda index /data/offline-channel。跑完之后目录里会多出repodata.json、repodata.json.bz2、repodata_from_packages.json这些文件。检查一下ls -lh /data/offline-channel/linux-64/repodata.json python -c import json d json.load(open(/data/offline-channel/linux-64/repodata.json)) print(包数量:, len(d[packages]) len(d.get(packages.conda, {}))) 包数量应该是几百往上如果输出 0说明文件没拷进这个子目录回去检查分类逻辑。注意如果 channel 里的包超过几千个repodata.json会变得很大加载会很慢。这种情况下建议只放项目实际需要的包不要图省事把整个公网源镜像下来。3.4 目标机的配置与安装命令把整个 channel 目录拷到目标机比如放在/opt/offline-channel然后写一份专用的.condarc不要改全局配置用-f指定更安全channels: - file:///opt/offline-channel - defaults channel_priority: strict offline: true pkgs_dirs: - /opt/conda-pkgs几个配置项的理由file:///opt/offline-channel注意是三个斜杠第一个是协议分隔符后面是绝对路径。写成两个斜杠 conda 会认为你是相对路径。channel_priority: strict严格按 channel 顺序取包避免 conda 在多个源之间反复计算依赖而导致极慢的求解。offline: true全局禁止联网这样 conda 不会浪费时间尝试连接任何源。单独指定pkgs_dirs避免写到用户家目录下多用户场景下会打架。安装命令conda create -n prodenv --file spec-explicit.txt --offline -y或者不指定版本直接在离线源里求解conda install -n prodenv numpy1.24 pandas2.1 --offline -y求解能不能成功取决于你的 channel 里包是否齐全。如果报PackagesNotFoundError别急着重做先把缺失的包名记下来回联网机补下载重新 index再拷一次。这种迭代过程是正常的第一次准备 channel 一般要往返两三次。3.5 用锁文件把版本钉死避免求解漂移离线源最大的隐患是今天装出来是 numpy 1.24半个月后补了新包求解器可能给你选出 1.26和同事的环境对不上。解决办法是用显式清单锁死一份清单就是一次完整的可复现安装。我们团队的做法是维护两个文件文件内容用途environment.yml松散约束只写名字和大致版本日常开发、给新同学用spec-explicit.txtEXPLICIT 完整 URL md5离线部署、生产环境、CI生成方式就是前面那条conda list --explicit。更细的做法是加--md5conda list -n prodenv --explicit --md5 lock/spec-explicit-md5.txt加了 md5 之后conda 安装时会逐个校验文件完整性这对内网传输特别有用——U 盘拷贝、跳板机中转都可能损坏文件有了校验就能第一时间发现而不是等到运行时莫名其妙崩溃。4. 方案三目录裸拷最后的兜底手段4.1 什么情况下只能这么干有两种情况我会放弃前两个方案一是环境里有从源码编译、无对应二进制包的组件比如某个手工打过补丁的数值库或者用特殊编译选项构建的扩展模块。这种包在离线源里根本不存在只能整个目录搬。二是环境原来的机器还在但目标机不方便重新装且两边系统版本、架构、glibc 完全一致。这种情况下裸拷反而最快。判断能不能裸拷先跑这两条对比uname -m ldd --version | head -1 python -c import sysconfig; print(sysconfig.get_platform())两台机器输出一致才有裸拷的基础。4.2 拷贝时用 rsync 而不是 cp环境目录里大量符号链接和小文件cp -r容易出问题用 rsync 并保留权限与链接属性rsync -aHAX --numeric-ids /opt/miniconda3/envs/myenv/ /data/envs/myenv/参数含义-a归档模式保留权限、时间、符号链接-H保留硬链接-A保留 ACL-X保留扩展属性--numeric-ids避免用户 ID 映射错乱。最后这个参数在内网跨机器搬迁时很重要两台机的用户名可能不一样。4.3 路径重写把旧前缀全换掉拷完之后环境里所有绝对路径还指向旧位置。先扫一遍看污染有多大OLD/opt/miniconda3/envs/myenv NEW/data/envs/myenv grep -rIl $OLD $NEW 2/dev/null | head -50 grep -rIl $OLD $NEW 2/dev/null | wc -l如果超过几百个文件说明污染严重说明这个环境里有很多脚本硬编码了路径。批量替换要谨慎先做备份cp -a $NEW ${NEW}.bak grep -rIl $OLD $NEW 2/dev/null | while read -r f; do # 跳过二进制文件 if file $f | grep -q text; then sed -i s|$OLD|$NEW|g $f fi done千万不要对.so、.pyc这类二进制文件做 sed会直接损坏文件。上面用file判断是不是文本就是为了避开这个雷。文本类文件改完之后还要单独处理几类特殊位置bin/下所有脚本的 shebang检查一下首行是否已是新路径lib/python3.x/site-packages/下的.pth文件conda-meta/*.json里的link.source、prefix字段——这个字段其实不影响运行但影响conda list的正确性etc/conda/activate.d/*.sh里的路径变量。4.4 别忘了把 pkgs 缓存也带过去裸拷环境只能解决用不能解决改。如果目标机以后要在这个环境里再装点什么就必须把包缓存一起搬过去否则任何conda install都会尝试联网。rsync -aHAX --numeric-ids /opt/miniconda3/pkgs/ /opt/conda-pkgs/然后在目标机的.condarc里指过去pkgs_dirs: - /opt/conda-pkgs offline: true之后conda install --offline somepkg就只会在本地缓存里找找到了直接链接找不到就明确报错不会卡在联网超时上。4.5 pip 装的东西要单独处理裸拷对 pip 包的容忍度比 conda 差。纯 Python 的包一般没问题带 C 扩展的包只要rpath没写死绝对路径也能用。真正会出问题的是三类用pip install -e装的可编辑模式.pth或__editable__文件指向源码目录源码不在就import失败用pip install --target装的路径记录在sys.path里依赖.so里的RPATH指向旧前缀的编译扩展。检查方法cd /data/envs/myenv/lib/python3.10/site-packages python - PY import os, subprocess, sys root os.getcwd() bad [] for dirpath, _, files in os.walk(root): for f in files: if f.endswith((.so, .pyd)): p os.path.join(dirpath, f) out subprocess.run([strings, p], capture_outputTrue, textTrue).stdout if /opt/miniconda3 in out: bad.append(p) print(\n.join(bad) or OK: 未发现残留旧路径) PY查出有残留的最省事的做法是在目标机上重新装一遍这个包——前提是你手里有 wheel 或源码包。离线环境下没有包就只能用patchelf改RPATHpatchelf --set-rpath /data/envs/myenv/lib some_ext.so这个命令要慎用改错了直接导致import段错误。改之前备份原文件。5. 常见故障速查与排查手法5.1 报错速查表下面这张表是我这几年离线部署时积累的按出现频率排报错信息真实原因处理方式CondaHTTPError: Connection refused还在尝试联网找包命令加--offline.condarc里设offline: truePackagesNotFoundError离线源里缺包或 repodata 没生成检查包是否在正确子目录重新跑conda indexbad interpreter: No such file or directoryshebang 还指向旧前缀执行conda-unpack或手工改首行GLIBC_2.xx not found目标机系统库太老换同构系统打环境或前置LD_LIBRARY_PATHModuleNotFoundError但conda list里有.pth或路径记录失效重装该包或修正.pthSolving environment卡很久channel 太多、离线源太大加channel_priority: strict精简离线源ChecksumMismatch传输过程文件损坏用带 md5 的显式清单重传Permission denied激活不了文件权限在拷贝中丢失rsync -a重拷或chmod -R urwXunsatisfiable dependencies涉及__glibc包要求的系统版本高于目标机在目标机同版本系统上准备包EnvironmentLocationNotFound前缀路径写错或环境被移动用绝对路径检查CONDA_PREFIX5.2 落地后的三分钟自检脚本我一直强调环境装完不等于能用。装完立刻跑一段自检把这个步骤固化进部署脚本能省掉后面大量沟通成本。source /data/envs/myenv/bin/activate python - PY import sys, platform, importlib print(Python:, sys.version.split()[0]) print(Prefix:, sys.prefix) print(Platform:, platform.platform()) # 换成你项目的核心依赖 must_have [numpy, pandas, scipy] for m in must_have: try: mod importlib.import_module(m) print(fOK {m:12} {getattr(mod, __version__, n/a)}) except Exception as e: print(fFAIL {m:12} {e}) PY # 确认没有残留旧路径 grep -rIl /opt/miniconda3 /data/envs/myenv 2/dev/null | head最后那个grep尤其重要输出为空才算干净。有输出的话说明还有文件指向旧路径按前面方案三的方法处理。5.3 几个我反复用到的实操心得心得一小文件传输最容易坏。环境里.so文件动辄几十 MB而repodata.json记录的是 md5一旦对不上整个安装就会中断。内网跳板机中转时特别容易出问题我现在的做法是拷完先算一遍校验和再对比# 源端 find /data/offline-channel -type f -name *.conda -o -name *.tar.bz2 | xargs md5sum /tmp/sums.txt # 目标端 md5sum -c /tmp/sums.txt心得二不要用 root 打包环境也不要改环境目录的所有者。conda 对权限比较敏感用 root 装完再切回普通用户经常出现conda-unpack执行失败、缓存目录不可写之类的问题。我现在的规范是用谁运行环境就用谁安装环境。心得三环境目录不要放在会被自动清理的位置。/tmp下建环境是最常见的失误机器重启、系统定期清理任务都会把它删掉然后你会发现所有虚拟环境都消失了还以为是 conda 坏了。放/opt/envs或/data/envs这类持久化目录。心得四conda-meta/history值得留下来。它记录了每次安装操作的时间与来源出问题时是唯一能回溯的线索。我一般会在部署脚本最后追加一行标记echo # offline-deploy $(date %F %T) from $(hostname) $CONDA_PREFIX/conda-meta/history以后有人在环境里发现奇怪的依赖翻一眼 history 就知道是哪次部署引入的。心得五三个方案可以混用。实际项目里我经常这么干用方案二准备基础环境用方案一打成一个整体包分发给现场机如果某个现场机有特殊编译的组件再把它单独用方案三覆盖进去。没有哪种方案是纯正的能解决问题就是好方案。我个人在实际操作中的体会是离线部署这件事里工具本身占的比重其实不大真正花时间的是那几件事搞清楚目标机的架构和 glibc 版本、把依赖清单导出得足够精确、把传输过程中的文件完整性校验做扎实。这三件事做在前面剩下的命令基本照着敲就行跳过它们再花哨的工具组合也会在某个深夜的报错里让你怀疑人生。